Isolate Vector Search

Scope searches to a single Knowledge instance when multiple instances share the same vector database.

When multiple Knowledge instances share the same vector database, searches return results from all instances by default. Set isolate_vector_search=True to scope each instance’s searches to its own data.

from agno.knowledge.knowledge import Knowledge
from agno.vectordb.pgvector import PgVector

vector_db = PgVector(
    table_name="shared_vectors",
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
)

# Only returns results from documents this instance inserted
knowledge = Knowledge(
    name="support-docs",
    vector_db=vector_db,
    isolate_vector_search=True,
)

How It Works

When isolate_vector_search=True:

1. Insert: Each document gets linked_to metadata set to the Knowledge instance’s name.
2. Search: A linked_to filter is automatically injected, so only matching documents are returned.

When isolate_vector_search=False (default):

1. Insert: No linked_to metadata is added.
2. Search: No linked_to filter is applied. Searches return results from all documents in the vector database.

When to Use

Scenario	isolate_vector_search
Single Knowledge instance	False (default)
Multiple instances, each with its own vector database	False (default)
Multiple instances sharing one vector database, need isolation	True

Example: Shared Database, Isolated Searches

from agno.agent import Agent
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.pgvector import PgVector

vector_db = PgVector(
    table_name="shared_vectors",
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
)

# Two knowledge instances sharing the same vector database
hr_knowledge = Knowledge(
    name="hr-docs",
    vector_db=vector_db,
    isolate_vector_search=True,
)

engineering_knowledge = Knowledge(
    name="engineering-docs",
    vector_db=vector_db,
    isolate_vector_search=True,
)

# Insert into each instance
hr_knowledge.insert(path="hr-policies/")
engineering_knowledge.insert(path="engineering-docs/")

# This agent only searches HR documents
hr_agent = Agent(knowledge=hr_knowledge, search_knowledge=True)

# This agent only searches engineering documents
eng_agent = Agent(knowledge=engineering_knowledge, search_knowledge=True)

Backwards Compatibility

isolate_vector_search defaults to False. Existing Knowledge instances behave exactly as before.

Existing data does not have linked_to metadata

Documents indexed before this flag existed do not have linked_to in their vector database metadata. When you enable isolate_vector_search=True, searches filter for linked_to=<name>. Documents without this metadata field will not match and will be invisible to the isolated search.

Enabling isolate_vector_search=True on a Knowledge instance with existing data will cause those documents to disappear from search results. You must re-index or manually update the metadata to restore them.

Migrating existing data

You have two options:

Option 1: Re-index your data

Re-insert all content with isolate_vector_search=True enabled. This adds linked_to metadata to every document.

knowledge = Knowledge(
    name="support-docs",
    vector_db=vector_db,
    isolate_vector_search=True,
)

# Re-insert all content. New documents will include linked_to="support-docs".
knowledge.insert(path="support-documents/")

Option 2: Update metadata directly in the vector database

If re-indexing is expensive, update the linked_to field directly in your vector database. Set it to the Knowledge instance’s name for all relevant rows.

-- Example for PgVector (PostgreSQL)
UPDATE shared_vectors
SET meta_data = jsonb_set(meta_data, '{linked_to}', '"support-docs"')
WHERE meta_data->>'linked_to' IS NULL;

The exact query depends on your vector database. The key is that each document’s metadata must contain "linked_to": "<knowledge-instance-name>" to be found by isolated searches.

Combining with Manual Filters

When isolate_vector_search=True, the linked_to filter is merged with any filters you pass explicitly:

# Searches for documents with linked_to="hr-docs" AND department="legal"
results = hr_knowledge.search(
    query="vacation policy",
    filters={"department": "legal"},
)

If you use list-based filters (e.g., EQ, IN), the linked_to filter is not automatically injected. Add it manually:

from agno.filters import EQ

results = hr_knowledge.search(
    query="vacation policy",
    filters=[EQ("linked_to", "hr-docs"), EQ("department", "legal")],
)

Instance Uniqueness

Each Knowledge instance must have a unique combination of name, database, and table. Two instances with the same name pointing to the same contents database and table will raise a ValueError at startup.

from agno.db.postgres import PostgresDb
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.pgvector import PgVector

contents_db = PostgresDb(
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
    knowledge_table="knowledge_contents",
)

vector_db = PgVector(
    table_name="shared_vectors",
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
)

# These two instances will conflict because they share the same
# name, contents_db, and table
knowledge_a = Knowledge(
    name="my-docs",
    contents_db=contents_db,
    vector_db=vector_db,
)

knowledge_b = Knowledge(
    name="my-docs",          # same name
    contents_db=contents_db,  # same database and table
    vector_db=vector_db,
)
# ValueError: Duplicate knowledge instances detected

To fix this, give each instance a unique name, or point them to different contents databases or tables.

Requirements

• The Knowledge instance must have a name set. Without a name, no linked_to metadata is added and no filter is applied, even when isolate_vector_search=True.
• The vector database must support metadata filtering. See Filtering for supported databases.

Next Steps

Task	Guide
Filter by other metadata	Filtering
Set up a vector database	Vector Databases
Track content metadata	Contents DB