Agent Memory

Agent Memory

Overview

Persistent memory lives exclusively in ~/.agents/memory/. Read the files before making any claim about prior state — never speculate about what they contain.

All files live in ~/.agents/memory/:

| File | Purpose | Cap | |------|---------|-----| | MEMORY.md | Standing facts: env conventions, toolchain quirks, decisions | ~800 tokens | | USER.md | User profile: preferences, style, things to avoid | ~500 tokens | | YYYY-MM-DD.md | Session notes: task discoveries, open questions | Keep short |

MEMORY.md and USER.md load into every session — keeping them within cap avoids burning context on every turn.

---

Before Every Task — Retrieve

1. Read MEMORY.md and USER.md in full (always small enough to cat whole) — if either doesn't exist yet, treat as empty, no prior state
2. Run BM25 search on dated files using terms relevant to this task
3. If index.db does not exist, skip step 2 — this is the first session

BM25 search (ranked results):

~/.agents/skills/agent-memory/search.py "your search terms"

Quick grep fallback (no index required):

rg -C 2 "keyword" ~/.agents/memory/

---

After Every Task — Persist

1. Write discoveries to ~/.agents/memory/YYYY-MM-DD.md
2. If a standing fact changed, update MEMORY.md or USER.md — match a substring of the section and replace it
3. Rebuild the BM25 index — a stale index causes missed context on future searches

Save entries that are non-obvious and won't go stale: root causes, workarounds, env constraints, one-line decisions with rationale, open questions you didn't resolve.

Skip entries already readable in the codebase. Saving config file contents or workflow steps creates duplicate state that drifts from the source of truth — read the file when needed instead.

Good MEMORY.md entry:

## Deploy pipeline
Self-hosted runners (not GitHub-hosted) — cache does NOT persist between runs.
Docker layer caching must be configured manually per workflow.

Bad MEMORY.md entry (skip — just duplicates the workflow file):

## GitHub Actions
Uses actions/setup-go@v4, actions/checkout@v3, runs go test ./...

Rebuild index:

~/.agents/skills/agent-memory/index.py

---

Save Operations

Search for an existing entry before adding — duplicates drift and cause confusion. Match by substring, not full text.

• Add — append under a concise heading
• Replace — match a substring of the section, overwrite it
• Remove — delete entries that are stale or wrong

When a persistent file nears its cap, consolidate first: merge related entries, drop what's no longer true.

---

Common Mistakes

| Mistake | Fix | |---------|-----| | Speculating about memory contents | Read the files first — never guess | | Inventing memory locations like kb/ or notes/ | Only ~/.agents/memory/ exists | | Skipping index rebuild after writing | Rebuild every time — stale index = missed context | | Saving what's already in the codebase | Read the source file when needed instead | | Adding a new entry when one already exists | Search first, update the existing entry |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dzianisv
• Source: dzianisv/skills
• License: MIT

Install and usage instructions live in the source repository linked above.