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.

1from kern.knowledge.knowledge import Knowledge
2from kern.vectordb.pgvector import PgVector
3
4vector_db = PgVector(
5    table_name="shared_vectors",
6    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
7)
8
9# Only returns results from documents this instance inserted
10knowledge = Knowledge(
11    name="support-docs",
12    vector_db=vector_db,
13    isolate_vector_search=True,
14)

How It Works

When isolate_vector_search=True:

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

When isolate_vector_search=False (default):

Insert: No linked_to metadata is added.
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

1from kern.agent import Agent
2from kern.knowledge.knowledge import Knowledge
3from kern.vectordb.pgvector import PgVector
4
5vector_db = PgVector(
6    table_name="shared_vectors",
7    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
8)
9
10# Two knowledge instances sharing the same vector database
11hr_knowledge = Knowledge(
12    name="hr-docs",
13    vector_db=vector_db,
14    isolate_vector_search=True,
15)
16
17engineering_knowledge = Knowledge(
18    name="engineering-docs",
19    vector_db=vector_db,
20    isolate_vector_search=True,
21)
22
23# Insert into each instance
24hr_knowledge.insert(path="hr-policies/")
25engineering_knowledge.insert(path="engineering-docs/")
26
27# This agent only searches HR documents
28hr_agent = Agent(knowledge=hr_knowledge, search_knowledge=True)
29
30# This agent only searches engineering documents
31eng_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.

Tip

Enabling isolate_vector_search=True with vector databases that don't have existing linked_to metadata will cause those documents to disappear from search results. You must re-index or manually update the metadata to restore them.

Combining with Manual Filters

When isolate_vector_search=True, the linked_to filter is automatically merged with any filters you pass, regardless of filter format:

1# Dict-based filters: linked_to is merged automatically
2results = hr_knowledge.search(
3    query="vacation policy",
4    filters={"department": "legal"},
5)
6# Searches for: linked_to="hr-docs" AND department="legal"

1# List-based filters (FilterExpr): linked_to is also injected automatically
2from kern.filters import EQ
3
4results = hr_knowledge.search(
5    query="vacation policy",
6    filters=[EQ("department", "legal")],
7)
8# Searches for: linked_to="hr-docs" AND 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.

1from kern.db.postgres import PostgresDb
2from kern.knowledge.knowledge import Knowledge
3from kern.vectordb.pgvector import PgVector
4
5contents_db = PostgresDb(
6    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
7    knowledge_table="knowledge_contents",
8)
9
10vector_db = PgVector(
11    table_name="shared_vectors",
12    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
13)
14
15# These two instances will conflict because they share the same
16# name, contents_db, and table
17knowledge_a = Knowledge(
18    name="my-docs",
19    contents_db=contents_db,
20    vector_db=vector_db,
21)
22
23knowledge_b = Knowledge(
24    name="my-docs",          # same name
25    contents_db=contents_db,  # same database and table
26    vector_db=vector_db,
27)
28# 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