claude-automemory

claude-automemory

Persistent session recall for Claude Code. Read-only access to your local transcripts at ~/.claude/projects/, surfaced via a SessionStart hook and a /recall slash command.

Adapted from dezgit2025/auto-memory by Desi Villanueva. Mental model, command taxonomy, and "RUN FIRST" instruction pattern are his — see NOTICE.

Status: v0.1.0 — personal use, single-author repo.

Install

From any Claude Code session:

/plugin marketplace add gabrielpc1190/claude-automemory
/plugin install claude-automemory@claude-automemory

The marketplace and plugin share the same name. Updates: /plugin marketplace update claude-automemory then reinstall.

What it does

Every time Claude Code starts (or after /clear / /compact), the hook injects a small "orient" snapshot: 10 most recent files in your cwd + 3 most recent sessions + a "RUN FIRST" instruction block telling the model to query the bundled CLI before falling back to grep.

You can also invoke /recall <query> manually to ask things like:

• /recall files --days 1
• /recall search "rate limiter"
• /recall show abc12345
• /recall list --global

Commands (CLI)

Run directly from Bash:

python3 "${CLAUDE_PLUGIN_ROOT}/bin/recall.py" <cmd>

Command	What it returns
orient	Files + sessions snapshot for this cwd. The hook calls this.
files	Files touched (Edit/Write/Read), dedup, recency-sorted.
list	Recent sessions: id, first user msg, turn count.
search <term>	Case-insensitive substring search across user/assistant text.
show <sid>	One session: first/last user msg, turn count, tool_uses.
plans	Lists ~/.claude/plans/.
health	4-dim status: dir exists, parseable count, query latency, freshness.
format-check	Samples records, reports fraction matching expected schema.

Common flags: --days N, --limit N, --global, --json, --debug.

Architecture

SessionStart hook  ──►  recall.py orient --hook  ──►  additionalContext (~50 tokens)
/recall slash      ──►  recall.py <args>          ──►  surfaces output to model
SKILL.md           ──►  tells model to prefer recall over grep
                                ▼
                    ~/.claude/projects/<cwd-encoded>/*.jsonl  (read-only)

bin/recall.py is a single-file stdlib script (no pip install). The plugin manifest registers the hook; nothing in ~/.claude/CLAUDE.md or ~/.claude/settings.json is modified.

Format drift

Claude Code's JSONL format may evolve. Run python3 bin/recall.py format-check --json periodically. If status is drift, update REQUIRED_FIELDS in recall.py. The plugin never blocks the session on drift — only warns.

Tests

python3 -m pytest tests/ -v --tb=short

CI runs on Ubuntu and Windows, Python 3.10/3.11/3.12.

Uninstall

/plugin uninstall claude-automemory@claude-automemory

Leaves no residue in ~/.claude/. The plugin only ever read.

License

MIT. See LICENSE and NOTICE.