Skip to main content
Glama
chinwe

compound-memory

by chinwe
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

memory_search

Search a shared memory store using hybrid lexical and vector recall to retrieve ranked facts, preferences, and conventions from past sessions.

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. 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': [...]} 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

TableJSON 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.6/5.0
Behavior5/5

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

With no annotations, the description carries full behavioral burden and does so richly: dual-channel vs lexical-only fallback, the meaning of the 'similarity' field per mode, that confidence/recency/type are only tie-breaks, default-scope semantics, the private-namespace reader requirement, the fail-closed project isolation, neighbor embedding behavior, and the returned shape {'hits': [...]} sorted by score.

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?

Front-loaded with 'Search memories' before the mechanism detail, which is good, but the body is a dense run-on of em-dash clauses mixing score semantics, scope rules, and debugging options without paragraphing or bullets. Nearly every clause carries information, but the packing makes it hard to scan and pushes the actionable usage rules behind implementation trivia.

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

Completeness4/5

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

For a 7-parameter search tool with no output schema and no annotations, the description is nearly complete: it documents return shape, ordering, scope defaults, and the downstream memory_feedback step. Only top_k's role (result count) is left implicit, which is minor given its descriptive name and default.

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

Parameters4/5

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

Schema coverage is 0%, so the description must compensate and largely does: ns, reader, explain, project, and include_neighbors all get concrete semantics beyond their terse titles, including a hard requirement on reader. The main gap is top_k, which is never mentioned in the description, though its name plus default is fairly self-evident.

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

Purpose5/5

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

States a specific verb+resource ('Search memories') and immediately characterizes the mechanism (BM25 + optional BGE vector fused via RRF). It also differentiates from siblings by naming memory_feedback and the adoption/feedback loop, so an agent can place it in the memory toolset without opening schemas.

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

Usage Guidelines5/5

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

Explicit when-to-use guidance for every optional parameter: default scope is '_shared' plus private namespace, pass ns explicitly to narrow to one namespace, omit project to get only global memories (fail-closed), reader REQUIRED when ns is 'agent-<name>', explain for debugging, include_neighbors=False to suppress neighbors. When-not conditions (project omission consequences, reader requirement) are spelled out.

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