Skip to main content
The 3ngram MCP server exposes the following unified search tools. Every entry is generated from the tool’s source signature and docstring, so this page never drifts from the backend.
Required parameters are marked with the required attribute. Optional parameters show their default value.
Search (canonical) · read-only · non-destructive · idempotent · closed-world Canonical 3ngram search across memories AND content chunks — use first. Fans one query across both stores, tags every hit with source_type, and returns a coverage envelope so callers stop pre-routing between specialist tools and stop silently filling results from unrelated indexed content when a requested repo/path isn’t indexed (#4123 AC). Each hit carries source_type ("memory" / "content_chunk") and a normalized score in [0, 1]. Per-leg scores are min-max normalized before merge so similarity_floor applies uniformly across stores. Ranking internals live in the existing sync DB helpers. Pass memory_ids=[...] for direct visible-id lookup (no embedding call); this absorbs the standalone get_memory(id) tool. Pair with include_lineage=True to also attach each decision memory’s supersession chain (ancestors + descendants via memories.replaces_memory_id); this absorbs the standalone get_decision_lineage tool (#4201). Lineage is silently ignored when memory_ids is not set (vector-search path) so agents can pass the flag unconditionally. Pass source_type="memory" or "content" to skip the other leg. Per ADR-002 §Q3, chunks already promoted to atomic memories via memories.promoted_from_chunk_id are hidden so content promoted into a standing reference isn’t double-counted. Pre-#2899 the FK column is absent and dedup becomes a no-op. Returns: str Source: backend/src/engram/mcp/tools/search/unified.py

​
Parameters

​
query
str
required
Natural-language query. Ignored when memory_ids is set.
​
limit
int
default:"10"
Max total results to return after merge (default 10).
​
source_type
Literal['memory', 'content', 'all']
default:"'all'"
"all" (default), "memory" or "content".
​
memory_ids
list[int] | None
default:"None"
Optional list of memory IDs for direct visible-id lookup. Skips embedding + vector search.
​
include_lineage
bool
default:"False"
When True together with memory_ids, attach the supersession chain for each decision memory hit. Walks memories.replaces_memory_id in both directions (ancestors + descendants), capped at depth 10. Ignored on the vector-search path (no memory_ids) and a no-op for non-decision memories.
​
memory_type
str | None
default:"None"
Memory leg only — decision/commitment/blocker/ preference/pattern/note/event/fact. Legacy: context -> note.
​
project
str | None
default:"None"
Memory leg only — restrict to a project tag.
​
status
str | None
default:"None"
Memory leg only — open/waiting/scheduled/resolved/ expired/overdue/archived. Default returns all active.
​
created_after
str | None
default:"None"
Memory leg only — ISO 8601 lower bound.
​
due_before
str | None
default:"None"
Memory leg only — ISO 8601 upper bound on due_date.
​
source
str | None
default:"None"
Memory leg only — manual/hook/mcp/auto memory origin.
​
tag
str | None
default:"None"
Memory leg only — exact tag match.
​
sort_by
str
default:"'auto'"
Memory leg only — auto/relevance/recency/hybrid/updated.
​
include_archived
bool
default:"False"
Memory leg only — include archived rows.
​
expand_clusters
str
default:"'auto'"
Memory leg only — always/auto/never; echoed for envelope parity (unified merge does not append siblings).
​
explain
bool
default:"False"
Echo retrieval metadata to the envelope.
​
atomic_only
bool
default:"False"
Memory leg only — atomic = TRUE rows (ADR-002 standing references). Content chunks are skipped.
​
scope
str | None
default:"None"
Optional "personal" / "work" filter, or "all" to opt out of scope binding. When unset and scope binding is enabled, the search defaults to your primary scope; pass "all" for the legacy cross-scope firehose.
​
source_filter
str | None
default:"None"
Content leg only — path substring (e.g. B3dmar/engram). When no chunks match, the value lands in coverage.requested_sources_not_found (#4123 AC).
​
content_source_type
str | None
default:"None"
Content leg only — "github" / "local".
​
include_low_confidence
bool
default:"False"
Content leg only — bypass per-leg floor.
​
similarity_floor
float
default:"0.3"
Post-merge floor (default 0.3, zero disables).