dezgit2025/auto-memory

auto‑memory – Session recall for AI coding agents

What it does

• Provides a tiny, zero‑dependency CLI (session‑recall and backend‑specific commands) that reads the local SQLite session store used by tools such as GitHub Copilot CLI, Claude Code, and the Codex CLI.
• Before reading, it checks the schema version of the store. If the store’s format has changed (e.g., a new OpenAI‑Codex release), the tool stops safely and can launch a repair workflow.
• Repairs are either a pre‑reviewed fix bundled with the package or an AI‑assisted fix that asks the Codex CLI (GPT‑6 Astra) to propose a new reader. The candidate is tested on synthetic data and must be approved by the user before being applied.
• All operations are read‑only; the original session databases are never modified unless the user explicitly applies a repair.

Why it matters

• AI coding agents lose context when their session‑store schema changes. Without a compatible reader, the agent appears to have “amnesia” and can’t recall prior work.
• auto‑memory restores that recall with a few dozen tokens per query (≈ 50 tokens for “last 10 sessions”), dramatically reducing the token budget spent on re‑explaining past work.

How to get it

• Install once with an isolated Python tool manager (recommended: pipx or uv). The README supplies exact commands for macOS (Homebrew Python 3.14) and Linux/WSL.
• After installation, run the health check for the backend you use, e.g.:

  session-recall health                     # Copilot CLI
  SESSION_RECALL_ENABLE_CLAUDE_BACKEND=1 session-recall-cc health   # Claude Code
  session-recall-codex schema-check        # Codex CLI
  

• Pin the GitHub tag v0.6.0 (the only released version) to avoid unintentionally pulling a newer, unreleased commit.

Typical workflow

1. Check compatibility – session-recall‑codex schema-check.
2. If compatible – query the store, e.g. session-recall list --json --limit 10.
3. If incompatible – start a repair with session-recall-codex-fix. The tool will:
   • Look for a bundled fix and apply it automatically, or
   • Generate an AI‑proposed fix, run synthetic tests, and present the diff.
4. Approve the candidate (session-recall-codex-fix approve …) and apply it. If something goes wrong, you can roll back with session-recall-codex-fix rollback ….

Supported backends

Backend	Status	Activation
GitHub Copilot CLI	✅ ready (default)	session-recall
Claude Code	🟡 optional (set env var)	session-recall-cc
Codex CLI	✅ recall + reviewed repair; experimental AI repair	session-recall-codex
VS Code / JetBrains / Neovim	🟡 optional (extra install steps)	see deploy/install-other-backends.md

Who should use it

• Developers who rely on AI coding assistants and want their agents to remember prior sessions without re‑prompting.
• Teams that run multiple AI backends (Copilot, Claude, Codex) and need a single, lightweight tool to expose the local session history.
• Anyone concerned about token‑budget waste caused by repeatedly re‑explaining past work.

Limitations

• The AI‑assisted repair path is experimental and currently only works on macOS (needs sandbox‑exec).
• The package does not provide a Homebrew formula; installation is via isolated Python environments.
• The tool is read‑only unless you explicitly apply a repair; it will never modify your original session DB without consent.

---

Quick start (for humans)

# Install (choose pipx or uv)
pipx install "auto-memory @ git+https://github.com/dezgit2025/auto-memory.git@v0.6.0"
# Verify installation
session-recall --version
# Run a health check for your backend
session-recall health                     # Copilot CLI example
# List the last 10 sessions (≈50 tokens)
session-recall list --json --limit 10

Quick start (for AI agents)

1. Read deploy/install.md and follow its step‑by‑step instructions.
2. Respect the requires-user-confirmation flags – ask before any file or shell‑rc mutation.
3. After install, run the appropriate health command and then use session-recall … to give the agent memory of past work.

---

License: MIT – free to use, modify, and redistribute.