An IDE-agnostic, zero-dependency memory store for AI agents. Agents use it to retain context — sessions, files touched, milestones, decisions — across session boundaries, and recall that context when a new session begins.
AI agents lose all context when a session ends. The next session starts blind: the agent doesn't know what files were changed yesterday, what decisions were made, or what was left to do.
auto-memory solves this by giving agents a self-managed, local store they write to during a session and query at the start of the next. It has no external dependencies, starts in milliseconds, and stores everything in a single SQLite file the agent fully controls.
It is designed to be called by agents, not by humans. Humans configure it once; agents use it on every turn.
# Preferred (isolated tool install, no venv management)
uv tool install .
# Alternative
pipx install .
# Verify
session-recall healthPython 3.10+ required. No other dependencies.
Data lives in a single SQLite database (~/.auto-memory/session-store.db by
default). Four tables:
| Table | What it stores |
|---|---|
sessions |
Work sessions with git context, agent ID, open/closed state |
tracked_files |
Files read, created, edited, or deleted during a session |
checkpoints |
Named milestones within a session |
memories |
Free-form text entries with full metadata + FTS5 for search |
memories_fts is a virtual FTS5 table that enables full-text search over
memory content, tags, and project.
These two fields are stored independently on every record and serve different purposes:
project — session-level, agent-provided.
Spans multiple repositories ("acme/api sprint-42", "auth-refactor").
Only set when --project is passed explicitly. NULL if omitted.
Never auto-detected.
git_repo — per-write, auto-detected from the working directory.
Fallback chain: git remote owner/repo → git root path → cwd → None
Stored automatically on EVERY write (retain, track-file, checkpoint,
session-start). No flag required.
Filter with --repo on read commands.
Use --project for named work contexts. Use --repo to filter by repository
regardless of which project name (if any) was associated.
| Command | Purpose | Key flags |
|---|---|---|
session-start |
Open a new work session, prints session ID | --agent, --project (optional) |
session-end <sid> |
Close a session | --summary |
retain "<text>" |
Store a free-form memory | --tags, --project, --repo, --agent, --session |
track-file <path> |
Record a file access | --tool (read/edit/create/delete), --repo, --session |
checkpoint |
Mark a milestone | --title (required), --overview, --session |
forget <id> |
Permanently delete a memory by ID | — |
git_repo is auto-detected from the working directory on every write. Use --repo to
override the detected value (e.g. when running from a different directory than the target repo).
| Command | Purpose | Key flags |
|---|---|---|
list |
List recent sessions | --project, --repo, --days, --limit, --json |
show <sid> |
Full session detail: files, checkpoints, memories | --json |
search "<query>" |
Full-text search over memories | --project, --repo, --tags, --content-prefix, --days, --limit, --json |
files |
List tracked files | --session, --project, --repo, --days, --json |
checkpoints |
List milestones | --session, --project, --repo, --days, --limit, --json |
memories |
Dump all memories as JSONL (one record per line) | --session, --project, --repo, --days, --limit |
repos |
Projects worked on, by session count | --days, --json |
health |
DB status: exists, schema valid, write+read round-trip | --json |
All read commands accept --json for machine-readable output. --repo and
--project can be combined or used independently.
# ── Session open ─────────────────────────────────────────────────────────────
# git_repo is auto-detected from cwd — no flag needed.
# --project is optional; use it to name multi-repo work (sprint, feature, etc.).
sid=$(session-recall session-start --agent cursor 2>/dev/null | awk '{print $2}')
# Named context for a cross-repo session:
sid=$(session-recall session-start --agent cursor --project "payment-v2-migration" \
2>/dev/null | awk '{print $2}')
# ── Recall prior context (before touching any code) ──────────────────────────
# Tier 1 (~50 tokens) — always run first
session-recall files --limit 10 --json
session-recall list --limit 5 --json
# Scope by repo (auto-detected value — no manual input needed)
session-recall files --repo acme/payments-api --limit 10 --json
# Scope by project name (only useful if you set --project consistently)
session-recall list --project "payment-v2-migration" --limit 5 --json
# Combine both filters
session-recall files --repo acme/api --project "payment-v2-migration" --json
# Tier 2 (~200 tokens) — when Tier 1 isn't enough
session-recall search "authentication" --days 5 --repo acme/api
# Tag-only search (query omitted — precise tag filter, no FTS)
session-recall search --tags "correction-ledger" --days 180
# Tag filter combined with FTS query
session-recall search "auth" --tags "decision"
# Content-prefix filter — only memories whose text starts with the given prefix
session-recall search --content-prefix "correction-ledger:" --days 180
# Combined: tag + content-prefix for maximum precision
session-recall search --tags "correction-ledger" --content-prefix "correction-ledger:" --days 180
# Tier 3 (~500 tokens) — full detail for one session
session-recall show $old_sid --json
# ── During work ───────────────────────────────────────────────────────────────
session-recall track-file src/auth/middleware.py --tool edit --session $sid
# git_repo auto-detected per write call
session-recall checkpoint \
--title "JWT middleware implemented" \
--overview "Added RS256 validation; rejects expired tokens with 401" \
--session $sid
# ── After important decisions ─────────────────────────────────────────────────
# Single-repo memory (git_repo set automatically):
session-recall retain \
"acme/api: chose RS256 over HS256 — RS256 allows public key verification without sharing secrets" \
--tags "auth jwt decision" \
--session $sid
# Cross-repo memory — name both repos in content, use --project:
session-recall retain \
"acme/api + acme/payments: renamed amount → amount_cents in shared contract" \
--tags "migration api payments breaking-change" \
--project "payment-v2-migration" \
--session $sid
# ── Session close ─────────────────────────────────────────────────────────────
session-recall session-end $sid \
--summary "JWT middleware done; 12 files changed; all tests pass"Environment variable (highest priority):
export SESSION_RECALL_DB=/path/to/custom.dbConfig file at ~/.auto-memory/config.ini:
[store]
db_path = ~/.auto-memory/session-store.db
[limits]
list_default_limit = 20
search_default_limit = 20
lookback_days = 30Priority: env var > config file > built-in defaults.
auto-memory is not responsible for wiring itself into an agent. That is the agent's or the user's responsibility. The general integration pattern:
-
At session open — run
session-recall session-startand store the printed session ID. Pass--project "name"only when the session spans multiple repos and you want a named context; otherwise omit it.git_repois auto-detected from the working directory — no flag needed. -
After modifying a file — run
session-recall track-file <path> --tool edit --session <sid>. -
After reading a file — optionally run
session-recall track-file <path> --tool read --session <sid>. -
At milestones — instruct the agent to call
session-recall checkpoint --title "..." --session <sid>when it finishes a meaningful unit of work. -
After decisions — instruct the agent to call
session-recall retain "..." --session <sid>after any non-obvious decision, bug fix, or discovery. Name the repository in the content. For cross-repo decisions, name all repos in the content and pass--project. -
At session close — run
session-recall session-end <sid> --summary "...". -
At the start of the next session — run the Tier 1 recall before touching code:
session-recall files --limit 10 --json # what was recently touched? session-recall list --limit 5 --json # what sessions exist? # Scope to a repo, a project, or both: session-recall files --repo acme/api --json session-recall files --project "sprint-42" --json session-recall files --repo acme/api --project "sprint-42" --json
See install/ for concrete wiring guides and ready-to-copy scripts:
install/cursor.md— Cursor IDE (hooks.json + rules file)install/standard-agent.md— any agent using open standards- Scripts:
install/standard/hooks/ - AGENTS.md snippet:
install/standard/agents-md-snippet.md
- Scripts:
For contributors and agents working on the auto-memory codebase itself, see AGENTS.md.