Agent memory and retrieval

Organizes reusable agent knowledge with source history, scope and freshness controls, then retrieves evidence suited to the current task.

agent-memory-retrieval

Team members using this skill

See how it helps

When is it useful?

Use it when agents need to remember past work without confusing projects or treating outdated conclusions as current facts.

What does it help you do?

Separates working, episodic, semantic and procedural memory.
Tracks provenance, workspace scope and stale or superseded facts.
Combines lexical and semantic search before reranking relevant evidence.

Try asking this

Design repository memory that stops quoting facts after their source changes. Change the documented API route, then ask the same question again. The answer should use the updated source and expose conflicting older memories.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

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:

Memory Tier	Scope & Lifetime	Storage Pattern	Examples
Working Memory	Single turn / active task	Prompt context + structured scratchpad state	Current goal, active plan steps, in-flight tool outputs
Episodic Memory	Session / past runs within a workspace	Append-only run transcripts + indexed checkpoint summaries	Past task outcomes, root causes of prior bugs, rejected approaches
Semantic Memory	Project / domain facts across runs	Relational/document store + hybrid FTS/vector index with provenance	Architecture invariants, API contracts, verified domain glossary
Procedural Memory	Reusable operational playbooks & skills	Versioned markdown/YAML templates or few-shot exemplars	Phase-specific skills, runbooks, project build/test commands

Provenance, Scoping & Staleness Control

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

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.
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.
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:

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.
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.
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.
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.

Included files 1

SKILL.md