Skip to content

Local Repository Memory for Coding Agents

Coding-agent sessions are usually ephemeral: useful decisions, failed approaches, and project-specific practices disappear when the next session starts. A lightweight, local-first memory layer can preserve that context without adopting a hosted observability platform.

A file-first memory model

Keep the durable, reviewed knowledge with the project and keep the noisy source material separate:

agent-harness/
  projects/<repo-id>/
    rules.md
    decisions.md
    lessons.md
    review-checklist.md
    sessions/
  scripts/
    capture-session
    distill-memory
    inject-context
  • Rules contain stable instructions such as test commands, conventions, and security boundaries.
  • Decisions record architectural or product choices and their rationale.
  • Lessons record repeatable failure modes and the preferred response.
  • Sessions contain structured raw notes: goal, changes, commands, test results, blockers, decisions, and follow-ups.

Track the approved documents in Git. Keep raw transcripts and generated session logs private or ignored by default: they grow quickly and can contain secrets, customer information, or untrusted text.

Capture, distill, approve

The useful pipeline is deliberately conservative:

  1. At the end of a session, write a compact structured note.
  2. Periodically give recent notes to a distillation agent.
  3. Ask it to propose—not directly make—changes to rules, decisions, or lessons.
  4. Have a human review the proposal before it becomes always-loaded context.

This avoids turning an agent's one-off mistake or prompt-injected transcript into a permanent project instruction. Retain only evidence-backed, broadly useful guidance, and scope it by repository, directory, or task type.

Hooks and agent integrations

Lifecycle hooks are a good automation boundary. They can inject project context at session start, checkpoint before compaction, record commands and test results at session end, and launch a periodic review workflow. They should not be the primary database: use a portable file format such as Markdown and JSONL so the harness remains usable across agents.

Agent Durable repository context Automation fit
Claude Code CLAUDE.md and .claude/rules/ Native hooks can capture session lifecycle events.
Gemini CLI project instruction and settings files Native hooks support lifecycle and tool automation.
Codex CLI AGENTS.md Use repository instructions and verify the installed version's hook support.
OpenCode AGENTS.md and project configuration Plugins and events suit a custom harness.
GitHub Copilot CLI repository instructions and skills Use scripts, CI, or wrappers where lifecycle interception is needed.

For portability, make AGENTS.md the shared durable contract and mirror the essential instructions into each agent's native configuration where necessary. Keep agent-specific hook adapters thin; they should read and write the same neutral session and memory formats.

When a larger memory system is justified

A single project normally does not need embeddings or a service. Git, Markdown, and a scheduled distillation command are transparent, searchable, and easy to review. Add semantic retrieval only when the corpus is too large to navigate with files and search. At that point, local deployments of tools such as Mem0 can provide retrieval while the human-approved rule files remain the source of truth.

Agent skills are complementary rather than a replacement for memory: use them for repeatable procedures such as PR review, release work, migrations, and incident response. Use the memory files for facts learned about this particular project.

Operational safeguards

  • Never automatically promote raw transcript text to instructions.
  • Redact credentials, tokens, and customer data before storage or retrieval.
  • Version approved memories and review their diffs like code.
  • Retrieve only the smallest context relevant to the current repository and task.
  • Treat PR review checklists as procedural memory and update them only after repeated evidence.

This gives a small team a practical, auditable memory system: local session capture, human-governed learning, and automatic context loading for the next coding session.