Retrieval Tools
Give your agents persistent memory with store, query, and delete operations.
On this page
Retrieval tools vs. Database tools
Connic provides two storage systems for agents. They serve different purposes and are often used together.
Stores text and finds it by meaning. A query for "cancellation rules" can surface a document titled "return and refund policy".
Ranks unstructured text such as documentation, FAQs, and notes by relevance.
Stores structured data and finds it by exact field values. Query with operators like $gt, $in, or $and against any field in any collection.
Supports exact lookups, field filters, counts, and record creation, updates, and deletion.
Retrieval tools let your agents store and retrieve information that persists across runs. Store documents, FAQs, or any text, then query it naturally. Queries rank relevant content by meaning instead of exact keywords.
Storing content is asynchronous. retrieval_store returns a queued job, and the content becomes searchable after that job finishes. Queries and metadata-filter deletes only include indexed entries.
Namespaces let you organize content into a hierarchy using dot-separated names (e.g., "policies.hr.leave", "products.pricing"). Querying a parent namespace also searches all sub-namespaces. Entry IDs are unique within a namespace. Max depth is 10 levels.
You can view, search, and manage all indexed content from the Retrieval page in your project dashboard.
Custom tool wrappers
Wrapper functions can expose names such as remember and recall while fixing namespaces or access rules. You can also list the predefined retrieval tools directly in YAML.
from connic.tools import retrieval_store, retrieval_query, retrieval_delete
async def remember(content: str, topic: str) -> dict:
"""Store information under a topic."""
return await retrieval_store(content=content, namespace=topic)
async def recall(question: str, topic: str | None = None) -> list:
"""Search indexed content for relevant information."""
result = await retrieval_query(question, namespace=topic)
return result["results"]
async def forget(entry_id: str, topic: str) -> dict:
"""Remove an entry from a topic."""
return await retrieval_delete(entry_id=entry_id, namespace=topic)Use the custom tools in the agent YAML:
version: "1.0"
name: my-agent
model: connic/gpt-5.6-terra
description: "Stores and retrieves project knowledge"
system_prompt: |
Use memory tools to store, recall, and remove project knowledge.
tools:
- memory.remember
- memory.recall
- memory.forgetParameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| query | string | required | Text used for semantic matching |
| namespace | string? | null | Namespace and descendants to search. Omit to search all namespaces |
| min_score | float | 0.3 | Minimum relevance score (0.0 to 1.0) |
| max_results | int | 3 | Requested result count, clamped to 1–20 |
| metadata_filter | dict? | null | MongoDB-style filter applied to entry metadata. Uses the same operators as db_find ($eq, $ne, $in, $gt, $exists, $or, …). Nested keys use dot notation. Each $in or $nin list accepts at most 1,000 values |
Return Value
Returns matching results with: content, entry_id, score (relevance 0-1), namespace, metadata
Examples
# Simple query
result = await retrieval_query("What is the refund policy?")
# Results contain matching content with similarity scores
for item in result["results"]:
print(f"[{item['score']:.0%}] {item['content'][:100]}...")# Filter by namespace
result = await retrieval_query(
query="How do I reset my password?",
namespace="support"
)
# Filter by metadata — same MongoDB-style operators as the database tools
# (\$eq, \$ne, \$gt, \$gte, \$lt, \$lte, \$in, \$nin, \$exists,
# \$regex, \$contains, \$elemMatch, \$and, \$or, \$nor, \$not).
# Bare values are equality shorthand.
result = await retrieval_query(
query="product availability",
namespace="products",
metadata_filter={
"product_id": "X",
"status": {"$in": ["active", "pending"]},
},
)
# Adjust score threshold and result count
result = await retrieval_query(
query="pricing information",
min_score=0.2, # Lower threshold = more results
max_results=10 # Return up to 10 results
)Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| content | string | required | The text content to store, queued for asynchronous indexing |
| entry_id | string? | auto | Custom ID for the entry (UUID generated if omitted) |
| namespace | string? | null | Category for organizing content |
| metadata | dict? | null | Additional key-value data to store |
Return Value
Returns: entry_id, job_id, status, queued, and success. Storage is asynchronous, so the entry becomes searchable after the indexing job completes.
Examples
# Simple store (auto-generated ID)
result = await retrieval_store(
content="The company refund policy allows returns within 30 days."
)
# Returns immediately with a queued job
# {"entry_id": "abc123...", "job_id": "...", "status": "pending", "queued": true, "success": true}# Store with custom ID for later updates
result = await retrieval_store(
content="Q1 sales target is $1M with focus on enterprise.",
entry_id="q1-sales-target",
namespace="planning",
metadata={"quarter": "Q1", "year": "2024"}
)
# Store user preferences
result = await retrieval_store(
content="User prefers dark mode and metric units.",
entry_id="user-preferences",
namespace="user_data"
)Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| entry_id | string? | null | ID of a single entry to delete. Omit when bulk-deleting by namespace |
| namespace | string? | null | Namespace to scope the deletion. Required for metadata-filter deletes; sub-namespaces are included |
| metadata_filter | dict? | null | MongoDB-style filter applied to entry metadata. Uses the same operators as db_find ($eq, $ne, $in, $or, …). Requires namespace. Each $in or $nin list accepts at most 1,000 values |
Return Value
Returns: ok (success), deleted_chunks (number of indexed chunks removed). Provide either entry_id, or a namespace (optionally with metadata_filter). Entry IDs are unique per namespace, so specify the namespace if the same ID exists in multiple.
Examples
# Delete a single entry by id
result = await retrieval_delete(entry_id="old-product-info")
# Delete a single entry scoped to a namespace
result = await retrieval_delete(
entry_id="q1-sales-target",
namespace="planning",
)
# Bulk delete by metadata — uses the same MongoDB-style filter syntax
# as the database tools, so operators like \$ne / \$in / \$not work
result = await retrieval_delete(
namespace="products",
metadata_filter={"product_id": "X"},
)
# Orphan cleanup pattern: re-ingest a source, then delete every entry
# in scope from previous runs (everything that isn't the current run_id).
# Run the delete only after the re-ingest jobs have completed: entries
# still being indexed keep their previous run_id and would be deleted.
result = await retrieval_delete(
namespace="confluence",
metadata_filter={
"root_page_id": page_id,
"run_id": {"$ne": current_run_id},
},
)
# Wipe an entire namespace subtree (sub-namespaces included)
result = await retrieval_delete(namespace="meetings")Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
| parent | string? | null | Parent namespace to list children of. If omitted, lists top-level namespaces |
| depth | int | 1 | How many levels deep to list (1 = direct children, 0 = all descendants, max 10) |
Return Value
Without parent: returns a list of namespace objects with name, entry_count, total_entry_count, has_children.
With parent: returns parent (info about the parent) and namespaces (list of children).
Examples
# List top-level namespaces
result = await retrieval_list_namespaces()
# Returns: [{"name": "policies", "entry_count": 5, "total_entry_count": 12, "has_children": true}, ...]
# Drill into a specific namespace
result = await retrieval_list_namespaces(parent="policies")
# Returns: {"parent": {...}, "namespaces": [{"name": "policies.hr", ...}, ...]}
# List all namespaces at all depths
result = await retrieval_list_namespaces(depth=0)Complete Agent Example
version: "1.0"
name: retrieval-agent
model: connic/gpt-5.6-terra
description: "Agent with persistent memory"
system_prompt: |
You are an assistant with access to a retrieval.
Always search the retrieval first before answering.
tools:
- retrieval_query
- retrieval_store
- retrieval_delete
- retrieval_list_namespaces