Skip to main content
Glama
chinwe

compound-memory

by chinwe
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

memory_search

Search stored facts, preferences, and conventions across shared, private, and project scopes; combines lexical and vector recall to return ranked memories with retrieval mode.

Instructions

Search memories. Fuses lexical (BM25) and, when the vec extra + model are installed, vector (BGE) recall via RRF; otherwise falls back to lexical only. The response always includes retrieval {mode, reason}: mode is vector or lexical, and reason is set when the vector channel is off or the last recall failed (embedder-unavailable, engine-unavailable, or degraded) so a lexical-only fallback is visible without a separate tool. Each hit's 'similarity' field carries the normalized RRF fusion score (fused/rrf_max) in dual-channel mode, or the normalized BM25 score in lexical-only (linear) mode; per-hit rank components and the evidence summary come via explain=true. Confidence/recency/type act only as a small tie-break. Default scope is _shared PLUS your own private 'agent-' namespace (when your identity is known via attested process id or explicit reader) — private hits surface automatically, no extra query needed. Pass ns explicitly ('_shared' or 'agent-') to search a single namespace. project: your workspace project slug — results span global memories plus that project's; omit it and ONLY global (untagged) memories are returned (fail-closed: project memories never leak into general sessions). Each hit embeds up to 3 trimmed one-hop neighbors (active only, project-filtered) unless include_neighbors=False. explain: optional debugging carrier — pass true to attach a per-hit 'explain' object (lexical/vector rank, RRF score, prior term breakdown, retrieval channel) plus an 'evidence' summary line (outcome counts, last_verified, origin); omitted by default so the default hit shape stays unchanged. reader: your own source agent id — REQUIRED when ns is 'agent-' (private namespace, readable only by its owner host). Returns {'hits': [...], 'count', 'retrieval'} sorted by score. Compounding rule: after actually adopting a hit, call memory_feedback (agent = your source id) — skipped feedbacks leave the store static.

Input Schema

NameRequiredDescriptionDefault
nsNo
queryYes
top_kNo
readerNo
explainNo
projectNo
include_neighborsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.3

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so thoroughly: it discloses the dual-channel vs lexical fallback, the retrieval {mode, reason} reporting, the fail-closed project scoping rule, the auth requirement (reader) for private namespaces, and that neighbors are attached by default. Nothing about destructive/auth/fallback behavior is left implicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded, but the middle collapses into a dense run of parenthetical clauses (score normalization, namespace resolution, neighbor trimming) that is hard to parse in one pass. Most sentences carry real payload, yet the wall-of-text packaging costs readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description supplies the return shape {'hits', 'count', 'retrieval'} plus per-hit field semantics (similarity, explain, neighbors). For a read tool with seven parameters and no structured docs, this is sufficient to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does for six of seven parameters: ns scope/defaults, reader's auth role, project's fail-closed semantics, explain's default-off payload, include_neighbors' one-hop trimming, and the similarity field's meaning. Only top_k goes unexplained, which is minor against the otherwise rich coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Search memories" states a specific verb and resource, and the body makes the retrieval semantics (hybrid lexical/vector with RRF fusion) concrete. It never contrasts itself with the sibling memory_get, so an agent must infer search-vs-fetch-by-id on its own.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear conditional guidance: pass ns explicitly to target a single namespace, omit project and only global memories return, reader is required for 'agent-<name>', and attach explain=true only for debugging. It also names memory_feedback as the required follow-up after adopting a hit. What is missing is an explicit statement of when to prefer this over memory_get.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools