Agent memory and retrieval

Agent Memory & Retrieval

Separate transient turn state from durable knowledge, and make every stored memory inspectable, scoped, attributable, and invalidatable. Untracked or unverified "long-term memory" silently poisons future runs when code or facts change.

Four-Tier Memory Architecture

Model memory explicitly by lifetime, mutability, and retrieval pattern:

Provenance, Scoping & Staleness Control

Never store bare assertions in semantic or episodic memory without metadata:

1. Mandatory memory metadata:
   • scope: Explicit tenant, workspace, project, or user boundary (workspace_id, repo_id, user_id)—never allow cross-tenant memory leakage.
   • source_provenance: Exact origin (file_path + git_blob_sha, run_id + turn_id, or human_confirmed).
   • created_at, last_verified_at, and ttl / confidence.
2. Invalidation & Superseding:
   • When a file or schema referenced by a memory entry changes (detected via git commit diff or mtime/hash mismatch), mark dependent semantic memories as stale or re-verify before injecting them into a prompt.
   • Support explicit supersedes_memory_id chains so updated decisions replace outdated facts instead of coexisting as contradictory entries in top-$k$ retrieval.
3. Write Gate Against Memory Poisoning:
   • Never persist raw claims extracted from untrusted external inputs (emails, web pages, third-party issues) directly into trusted long-term instructions or procedural memory.
   • Distinguish verified outcomes (e.g., a fix that passed tests and review) from unverified hypotheses made mid-debugging.

Hybrid Retrieval Pipeline for Agents

Pure vector similarity fails on exact identifiers, error codes, symbol names, and file paths:

1. Hybrid lexical + semantic search: Combine BM25 / full-text search (plus exact symbol/trigram matching for code) with dense embedding similarity using Reciprocal Rank Fusion (RRF) or weighted score normalization.
2. Structure-aware chunking: Chunk source code along AST declarations (functions, classes, types with imports/file header context) and documentation along section headings (H1 > H2 > H3 breadcrumb prefix) rather than arbitrary fixed character windows.
3. Metadata pre-filtering & reranking: Filter by workspace_id, language, path prefix, and recency before scoring, then rerank top candidates (e.g., top 30 $\rightarrow$ top 6) and deduplicate overlapping spans before injecting into the prompt.
4. Agentic search over static RAG: Give the agent targeted retrieval tools (search_lexical, search_semantic, read_symbol, read_file_range) so it can iteratively refine queries and inspect surrounding context when initial retrieval is insufficient.