Gateway Module — `agent-memory/`

1. Purpose

The agent-memory module owns each CyberShinobi agent's private domain memory — the four learning tiers (task_blueprint, skill_heuristic, domain_pattern, lesson_learned) committed post-dispatch. It provides hybrid retrieval (Voyage vector search + FTS5 BM25 fused by reciprocal rank fusion), embedding-based deduplication on commit, a composite relevance score, and two distinct peer-read surfaces: queryPeer (literal single-agent equality) and queryPeerAny (cross-agent scan, caller-excluded upstream). Agents write only their own namespace; peer reads never increment access counts. It is consumed by the context module's assembly fanout.

2. File Inventory

3. Public API Surface

REST Endpoints (mount: index.ts:737 → /api/agent-memory)

MCP Tools

commit_agent_memory / commit_agent_memory_raw (→ /commit, raw canonical); read-path served by peer/query calls surfaced through assemble_context fanout, not a dedicated MCP tool. queryPeerAny has no REST/MCP surface of its own — it is invoked internally by the context module adapter.

4. Internal API

createAgentMemoryLayer(db, embeddingProvider, activityRepo?) → {repo, router}. AgentMemoryRepository methods: commit, query, queryPeer, queryPeerAny, listByAgent, countMemoriesSince. queryPeerAny is exported on the repo interface but has no route — consumed by context/index.ts:createPeerMemorySearchAdapter.

5. Background Services

None.

6. Data Contracts

Zod schemas in types.ts:

• CommitAgentMemoryInputSchema: agent_name, content, memory_type (4-enum), task_context? ({task_description, skills_used[], outcome: success|partial|failed, mission_namespace?}).
• QueryAgentMemoryInputSchema: agent_name, query, memory_type?, limit? (≤20).
• QueryPeerMemoryInputSchema: target_agent (min 1 — literal equality, D27 retired the '*' wildcard), query, memory_type?, limit? (≤10).
• QueryPeerAnyMemoryInputSchema: query, memory_type?, limit? (≤10) — no target_agent.
• ListAgentMemoryInputSchema: agent_name, memory_type?, limit? (≤100 — D1422 tightened from 500), offset?.
• PendingReviewQuerySchema: z.record(string, ISO-datetime).

Composite relevance score (D23 PR-2 rebalance): normalizedRrf*0.625 + accessFrequencyBoost*0.25 + outcomeBoost*0.125 — recency term removed (owned by the context uniform scoring funnel). PeerMemoryResult retains created_at (D23 PR-5 fix — its absence poisoned context/index.ts recency to NaN).

7. Dependencies

• Gateway modules: memory/types.js (EmbeddingProvider), activity/repository.js (ActivityRepository, optional), shared/search-utils.js (buildFts5Query, reciprocalRankFusion), shared/zod-error.js.
• External: better-sqlite3 (+ sqlite-vec virtual table agent_memory_vec, FTS5 agent_memory_fts), express, zod. Voyage embeddings via the injected provider.
• Environment variables: none directly (Voyage key loaded by the memory module's provider).

8. Test Coverage

9. Known Limitations

• safeEmbed degrades silently to keyword/FTS-only when the Voyage provider throws (console.warn + null). Commit still proceeds without a vector — dedup is skipped that call.
• Dedup only fires within the same agent (row.agent_name === input.agent_name guard) and only against the top-5 nearest neighbours with distance <0.2; near-duplicates just past the threshold or beyond k=5 are stored as new rows.
• commit_agent_memory still exposes a legacy permissive-flat MCP tool alongside the raw twin (see mcp module) — nested task_context is exposed to the client-cache staleness class on the legacy path.

10. Change History