[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1141":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":14,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":9,"pushedAt":9,"updatedAt":25,"readmeContent":26,"aiSummary":27,"trendingCount":15,"starSnapshotCount":15,"syncStatus":16,"lastSyncTime":28,"discoverSource":29},1141,"auto-memory","dezgit2025\u002Fauto-memory","dezgit2025","Your AI coding agent never forgets — progressive session recall CLI",null,"Python",356,37,12,6,0,2,5,17,4.74,"MIT License",false,"main",true,[],"2026-06-12 02:00:23","# auto-memory\n\n## Your AI coding agent has amnesia. Here's the fix.\n\n*~1,900 lines of Python. Zero dependencies. Saves you an hour a day.*\n\n> Built by [Desi Villanueva](https:\u002F\u002Fgithub.com\u002Fdezgit2025)\n\n[![PyPI](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fauto-memory)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fauto-memory\u002F)\n[![CI](https:\u002F\u002Fgithub.com\u002Fdezgit2025\u002Fauto-memory\u002Factions\u002Fworkflows\u002Ftest.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fdezgit2025\u002Fauto-memory\u002Factions\u002Fworkflows\u002Ftest.yml)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](LICENSE)\n[![Python 3.10+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.10+-blue.svg)](https:\u002F\u002Fwww.python.org)\n[![Zero Dependencies](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdependencies-0-brightgreen)](pyproject.toml)\n[![Tests](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Ftests-90%20passed-brightgreen)]()\n[![Discussions](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F📢_Updates-Discussions-blue)](https:\u002F\u002Fgithub.com\u002Fdezgit2025\u002Fauto-memory\u002Fdiscussions)\n\n\u003C!-- AGENTIC-INSTALL-PROTOCOL: v1\n     Files: deploy\u002Finstall.md, deploy\u002Finstall-other-backends.md, deploy\u002Finstall-claude-code.md\n     Entry: Read deploy\u002Finstall.md\n-->\n\n### 🆕 What's New in v0.4.0\n\n**Claude Code support** — `session-recall-cc` reads Claude Code JSONL sessions and builds an FTS5 index for structured recall. `pip install auto-memory[claude]` to get started. [Full changelog →](CHANGELOG.md)\n\n**Zero-dependency CLI that turns Copilot CLI's local SQLite into instant recall — no MCP server, no hooks, read-only, schema-checked. ~50 tokens per prompt.**\n\n### Works With\n\n| Backend | Status | How to enable |\n|---------|--------|--------------|\n| **GitHub Copilot CLI** | ✅ default | Already on — `pip install auto-memory` is all you need |\n| **Claude Code** | 🟡 opt-in | `pip install auto-memory[claude]` — [Full setup →](deploy\u002Finstall-claude-code.md) |\n| **VS Code** | 🟡 opt-in | [Enable in 30 seconds →](deploy\u002Finstall-other-backends.md#32--vs-code-backend) |\n| **JetBrains** | 🟡 opt-in | [Enable →](deploy\u002Finstall-other-backends.md#33--jetbrains-backend) |\n| **Neovim** | 🟡 opt-in | [Enable →](deploy\u002Finstall-other-backends.md#34--neovim-backend) |\n\n> **Claude Code user?** `pip install auto-memory[claude] && export SESSION_RECALL_ENABLE_CLAUDE_BACKEND=1` — then ask your agent to read [`deploy\u002Finstall-claude-code.md`](deploy\u002Finstall-claude-code.md) for full integration.\n\n> **VS Code user?** Ask your agent to read [`deploy\u002Finstall-other-backends.md`](deploy\u002Finstall-other-backends.md) — it walks through detection, env var setup, and verification automatically.\n\n**Coming soon:** Cursor · Codex\n\n---\n\n### Quickstart\n\n```bash\npip install auto-memory           # or: git clone + .\u002Finstall.sh\npip install --upgrade auto-memory # upgrade to latest\nsession-recall health          # verify it works\n```\n\nNow give your agent a memory. See the **🤖 Agentic Install** section below for agent-driven setup, or follow [`deploy\u002Finstall.md`](deploy\u002Finstall.md) manually.\n\n### 📋 Example: Remember Your Last 10 Sessions\n\nWant to recall the last 10 sessions you worked on, which project folder, branch, and what you did? Add this prompt to your agent instructions:\n\n```\nUse `session-recall list --json --limit 10` to show my last 10 sessions.\nDisplay: date, time, full session_id, summary, branch, turns count, project folder.\nFormat as a table.\n```\n\nYour agent runs it and gets:\n\n```\n #  │ Date  │ Time  │ Session ID                                 │ Summary                    │ Branch            │ Project                  │ Turns\n────┼───────┼───────┼────────────────────────────────────────────┼────────────────────────────┼───────────────────┼──────────────────────────┼──────\n 1  │ 05-01 │ 14:32 │ a1b2c3d4-e5f6-7890-abcd-ef1234567890       │ Refactor Auth Module       │ main              │ ~\u002FProjects\u002Facme-api      │   12\n 2  │ 05-01 │ 11:15 │ b2c3d4e5-f6a7-8901-bcde-f12345678901       │ Fix CI Pipeline            │ feat\u002Foauth2       │ ~\u002FProjects\u002Facme-api      │   28\n 3  │ 04-30 │ 22:48 │ c3d4e5f6-a7b8-9012-cdef-123456789012       │ Add Redis Caching          │ feat\u002Fcache-layer  │ ~\u002FProjects\u002Facme-api      │   35\n 4  │ 04-30 │ 16:05 │ d4e5f6a7-b8c9-0123-defa-234567890123       │ Debug WebSocket Timeout    │ main              │ ~\u002FProjects\u002Frealtime-chat │    8\n 5  │ 04-29 │ 09:33 │ e5f6a7b8-c9d0-1234-efab-345678901234       │ Write Migration Script     │ feat\u002Fdb-v2        │ ~\u002FProjects\u002Frealtime-chat │   42\n 6  │ 04-29 │ 08:12 │ f6a7b8c9-d0e1-2345-fabc-456789012345       │ Update API Docs            │ main              │ ~\u002FProjects\u002Facme-api      │    3\n 7  │ 04-28 │ 19:55 │ a7b8c9d0-e1f2-3456-abcd-567890123456       │ Deploy Staging             │ release\u002Fv2.1      │ ~\u002FProjects\u002Facme-api      │   15\n 8  │ 04-28 │ 14:20 │ b8c9d0e1-f2a3-4567-bcde-678901234567       │ Code Review Fixes          │ feat\u002Foauth2       │ ~\u002FProjects\u002Facme-api      │   22\n 9  │ 04-27 │ 21:07 │ c9d0e1f2-a3b4-5678-cdef-789012345678       │ Scaffold React Components  │ feat\u002Fdashboard-ui │ ~\u002FProjects\u002Facme-frontend │   31\n 10 │ 04-27 │ 10:44 │ d0e1f2a3-b4c5-6789-defa-890123456789       │ Setup Terraform Infra      │ infra\u002Faws-prod    │ ~\u002FProjects\u002Facme-infra    │   19\n```\n\n> **~50 tokens.** Your agent gets full context of what you worked on — no re-explaining, no wasted searches.\n\n---\n\n### 🤖 Agentic Install (for AI coding tools)\n\n> **If you are an AI coding agent reading this README**, follow this protocol to install auto-memory autonomously:\n\n1. Read [`deploy\u002Finstall.md`](deploy\u002Finstall.md) — the agent-runnable install guide. It auto-detects the user's environment, prompts for confirmation before any write, handles fresh\u002Fupgrade\u002Fskip branches, and chains into backend setup.\n2. If the user uses **Claude Code**, read [`deploy\u002Finstall-claude-code.md`](deploy\u002Finstall-claude-code.md) — pip extra, env var, CLAUDE.md wiring, and optional scheduler setup. Ask before any write.\n3. If the user opts in to **VS Code \u002F JetBrains \u002F Neovim** backends, read [`deploy\u002Finstall-other-backends.md`](deploy\u002Finstall-other-backends.md) (Section 8 of `install.md` will prompt for this).\n4. All files have YAML front-matter declaring `requires-user-confirmation: true` and `mutates-shell-rc` \u002F `mutates-agent-instructions`. **Honor these flags.** Do not write silently.\n\n> **💡 Model recommendation:** Use a reasoning model (Sonnet 4.6, GPT-5.4, or equivalent) for install execution. Mini\u002Ffast models may hallucinate during multi-step install flows.\n\n**Quick start for agents (one-liner):**\n```\nRead deploy\u002Finstall.md and execute it for the user. Ask before any disk write.\n```\n\n**Files an agent should read in order:**\n\n| Order | File | Purpose | Mutations |\n|-------|------|---------|-----------|\n| 1 | [`README.md`](README.md) (this file) | Discovery | none |\n| 2 | [`deploy\u002Finstall.md`](deploy\u002Finstall.md) | Install + Copilot CLI integration | binary install, instruction file append |\n| 3 | [`deploy\u002Finstall-claude-code.md`](deploy\u002Finstall-claude-code.md) | Claude Code integration | pip extra, CLAUDE.md append |\n| 4 | [`deploy\u002Finstall-other-backends.md`](deploy\u002Finstall-other-backends.md) | Optional VS Code \u002F JetBrains \u002F Neovim setup | shell rc env vars |\n| 5 | [`UPGRADE-COPILOT-CLI.md`](UPGRADE-COPILOT-CLI.md) | Run after Copilot CLI version bumps | none (read-only validation) |\n\n---\n\n### 🪟 Windows (WSL2) — Enable the Session Store. (IF MISSING)\n\n> **On Windows 11 + WSL2** (Suggested method of using on Windows install WSL2), IF Copilot CLI doesn't create `session-store.db`   \n> You must enable it first — otherwise you'll get `error: database not found`.\n\n### Missing Session Store Error Workaround— Enable the Session Store. \nInside any Copilot CLI session, run:\n\n```\n\u002Fexperimental\n```\n\nSelect **SESSION_STORE** to enable it. This turns on the SQLite-based session store for cross-session history, file tracking, and search.\n\nVerify it worked:\n\n```bash\nls ~\u002F.copilot\u002Fsession-store.db    # should exist after your next session\n```\n\n> **Note:** This is a one-time setup. Once enabled, the session store persists across all future sessions.\n\n---\n\n## The Problem\n\nEvery AI coding agent ships with a big number on the box. 200K tokens. Sounds massive. Here's what actually happens:\n\n```\n200,000  tokens — context window (theoretical max)\n120,000  tokens — effective limit before context rot kicks in (~60%)\n -65,000  tokens — MCP tools\n -10,000  tokens — instruction files\n=========\n ~45,000  tokens — what you ACTUALLY have before quality degrades\n```\n\nLLMs don't degrade gracefully — once you cross roughly **60% of the context window**, the model starts losing coherence. The industry calls it \"lost in the middle\": attention goes to the beginning (instructions) and the end (recent turns), but your actual working context in the middle gets progressively fuzzier.\n\nI timed it over a week: **68 minutes per day** lost to re-orientation after compactions and new sessions.\n\n> It's a **death spiral of diminishing context** — each compaction leaves the agent slightly dumber, which burns more tokens explaining things, which triggers the next compaction sooner.\n\n### The Compaction Tax\n\nEvery 20–30 turns, the context warning hits and you get two bad choices: ignore it and watch the agent hallucinate, or run `\u002Fcompact` and watch it lobotomize itself into a tidy two-paragraph summary of a 30-minute investigation. Either way you lose five minutes re-narrating your own project back to the agent like it's a new hire. That's not a workflow — that's a hamster wheel.\n\n## The 200x ROI\n\nHere's the cost comparison that made me build this:\n\n| Operation | Tokens | What you get |\n|-----------|--------|-------------|\n| `grep -r \"auth\" src\u002F` | ~5,000-10,000 | 500 results, mostly irrelevant |\n| `find . -name \"*.py\"` | ~2,000 | Every Python file, no context |\n| Agent re-orientation | ~2,000 | You re-explaining yesterday |\n| **`auto-memory files --json --limit 10`** | **~50** | **Exactly the 10 files you touched yesterday** |\n\n**50 tokens vs 10,000 — a 200x improvement.**\n\n## Before & After\n\n**Before auto-memory** — new session on a project:\n\n```\nYou: Fix the failing test in the auth module\n\nAgent: Let me explore the project structure...\n       $ find . -name \"*.py\" | head -50           ← 2K tokens\n       $ grep -r \"test.*auth\" tests\u002F              ← 5K tokens\n       $ cat tests\u002Ftest_auth.py                    ← 3K tokens\n       $ cat src\u002Fauth\u002Fhandler.py                   ← 2K tokens\n       I see several test files. Which test is failing?\n\nYou: The one we were working on yesterday, the token refresh edge case\n\nAgent: Let me search for that...\n       $ grep -r \"refresh\" tests\u002F                  ← 4K tokens\n       ...\n```\n\nTotal: ~16K tokens burned, 8 minutes elapsed, agent still isn't oriented.\n\n**After auto-memory** — same scenario:\n\n```\nYou: Fix the failing test in the auth module\n\nAgent: [auto-recall: auto-memory files --json --limit 10]\n       → src\u002Fauth\u002Frefresh.py, tests\u002Ftest_refresh_edge_cases.py,\n         src\u002Fauth\u002Ftoken_store.py (last touched 14h ago)\n\n       [auto-recall: auto-memory list --json --limit 3]\n       → Yesterday: \"Fixed token refresh race condition, one edge case\n         test still failing on expired token + network timeout combo\"\n\n       I can see from your last session that test_refresh_edge_cases.py\n       has a failing test for the expired token + network timeout case.\n       Let me look at that specific test...\n       $ cat tests\u002Ftest_refresh_edge_cases.py      ← 1K tokens (targeted)\n```\n\nTotal: ~1.1K tokens, 30 seconds, agent is immediately productive.\n\n## How it compares\n\n| Approach | Dependencies | Writes to DB | Setup | Agent-native |\n|----------|-------------|-------------|-------|-------------|\n| **auto-memory** | None (stdlib) | ❌ Read-only | `pip install` | ✅ Instruction-file |\n| MCP server | Node.js runtime | Varies | Server config | ❌ Protocol layer |\n| Custom hooks | Varies | Often yes | Hook scripts | ❌ Event-driven |\n| Manual grep | None | ❌ | None | ❌ Manual |\n\n## Mental Model: RAM vs Disk\n\n- **Context window = RAM.** Fast, limited, clears on restart.\n- **session-store.db = Disk.** Persistent, searchable, grows forever.\n\nauto-memory is the **page fault handler** — it pulls exact facts from disk in ~50 tokens when the agent needs them.\n\n**It's not unlimited context. It's unlimited context *recall*.** In practice, same thing.\n\n## Design\n\n```\n┌─────────────────────────────────────────────────┐\n│  copilot-instructions.md                        │\n│  \"Run auto-memory FIRST on every prompt\"         │\n└──────────────────┬──────────────────────────────┘\n                   │ agent reads instruction\n                   ▼\n┌─────────────────────────────────────────────────┐\n│  auto-memory CLI                                │\n│  (pure Python, zero deps, read-only)            │\n└──────────────────┬──────────────────────────────┘\n                   │ SELECT ... FROM sessions\n                   ▼\n┌─────────────────────────────────────────────────┐\n│  ~\u002F.copilot\u002Fsession-store.db                    │\n│  (SQLite + FTS5, owned by Copilot CLI binary)   │\n└─────────────────────────────────────────────────┘\n```\n\n- **Zero dependencies** — stdlib only (sqlite3, json, argparse)\n- **Read-only** — never writes to `~\u002F.copilot\u002Fsession-store.db`\n- **WAL-safe** — exponential backoff retry on SQLITE_BUSY (50→150→450ms)\n- **Schema-aware** — validates expected schema on every call, fails fast on drift\n- **Telemetry** — ring buffer of last 100 invocations for concurrency monitoring\n\n## Works with Claude Code (opt-in)\n\nIn addition to GitHub Copilot CLI, `auto-memory` can read [Claude Code](https:\u002F\u002Fdocs.anthropic.com\u002Fclaude-code) session logs from `~\u002F.claude\u002Fprojects\u002F`. This ships as a separate CLI binary (`session-recall-cc`) that is **off unless explicitly enabled** — Copilot CLI users pay zero cost.\n\n### Quick install (3 steps)\n\n```bash\npip install auto-memory[claude]\nexport SESSION_RECALL_ENABLE_CLAUDE_BACKEND=1\nsession-recall-cc health\n```\n\n### Optional: pre-warm scheduler\n\n> Skip this unless you want consistent sub-100ms latency. The CLI already does on-demand indexing (~50ms after the first run).\n\nIf you have the repo cloned, the installer auto-detects your OS:\n\n```bash\nbash scripts\u002Finstall-claude-sidecar.sh --install    # auto-detects OS\nbash scripts\u002Finstall-claude-sidecar.sh --status     # check state\nbash scripts\u002Finstall-claude-sidecar.sh --uninstall  # remove\n```\n\nOtherwise, pick your OS below:\n\n#### macOS (Intel & Apple Silicon)\n\nUses `launchd` — Apple's native scheduler. Survives sleep\u002Fwake, auto-runs at login.\n\n```bash\nPYTHON3=\"$(command -v python3)\"\ncat > ~\u002FLibrary\u002FLaunchAgents\u002Fcom.session-recall-cc.sidecar.plist \u003C\u003CEOF\n\u003C?xml version=\"1.0\" encoding=\"UTF-8\"?>\n\u003C!DOCTYPE plist PUBLIC \"-\u002F\u002FApple\u002F\u002FDTD PLIST 1.0\u002F\u002FEN\"\n  \"http:\u002F\u002Fwww.apple.com\u002FDTDs\u002FPropertyList-1.0.dtd\">\n\u003Cplist version=\"1.0\">\u003Cdict>\n  \u003Ckey>Label\u003C\u002Fkey>\u003Cstring>com.session-recall-cc.sidecar\u003C\u002Fstring>\n  \u003Ckey>ProgramArguments\u003C\u002Fkey>\u003Carray>\n    \u003Cstring>$PYTHON3\u003C\u002Fstring>\u003Cstring>-m\u003C\u002Fstring>\n    \u003Cstring>session_recall.providers.claude_code.sidecar\u003C\u002Fstring>\n    \u003Cstring>--once\u003C\u002Fstring>\n  \u003C\u002Farray>\n  \u003Ckey>EnvironmentVariables\u003C\u002Fkey>\u003Cdict>\n    \u003Ckey>SESSION_RECALL_ENABLE_CLAUDE_BACKEND\u003C\u002Fkey>\u003Cstring>1\u003C\u002Fstring>\n    \u003Ckey>PATH\u003C\u002Fkey>\u003Cstring>\u002Fopt\u002Fhomebrew\u002Fbin:\u002Fusr\u002Flocal\u002Fbin:\u002Fusr\u002Fbin:\u002Fbin\u003C\u002Fstring>\n  \u003C\u002Fdict>\n  \u003Ckey>StartInterval\u003C\u002Fkey>\u003Cinteger>300\u003C\u002Finteger>\n  \u003Ckey>RunAtLoad\u003C\u002Fkey>\u003Ctrue\u002F>\n  \u003Ckey>StandardOutPath\u003C\u002Fkey>\u003Cstring>$HOME\u002F.claude\u002F.sr-sidecar.log\u003C\u002Fstring>\n  \u003Ckey>StandardErrorPath\u003C\u002Fkey>\u003Cstring>$HOME\u002F.claude\u002F.sr-sidecar.err.log\u003C\u002Fstring>\n\u003C\u002Fdict>\u003C\u002Fplist>\nEOF\nlaunchctl load -w ~\u002FLibrary\u002FLaunchAgents\u002Fcom.session-recall-cc.sidecar.plist\n```\n\n**Verify:** `launchctl list | grep session-recall-cc`\n**Uninstall:** `launchctl unload -w ~\u002FLibrary\u002FLaunchAgents\u002Fcom.session-recall-cc.sidecar.plist && rm ~\u002FLibrary\u002FLaunchAgents\u002Fcom.session-recall-cc.sidecar.plist`\n\n#### Linux \u002F Windows WSL2\n\nUses `cron` — works on any distro and WSL2.\n\n```bash\n(crontab -l 2>\u002Fdev\u002Fnull; echo \"*\u002F5 * * * * env SESSION_RECALL_ENABLE_CLAUDE_BACKEND=1 $(command -v python3) -m session_recall.providers.claude_code.sidecar --once >> ~\u002F.claude\u002F.sr-sidecar.log 2>&1\") | crontab -\n```\n\n**Verify:** `crontab -l | grep session-recall`\n**Uninstall:** `crontab -l | grep -v session-recall | crontab -`\n\n> [!TIP]\n> Full details (Windows Task Scheduler, interval tuning, troubleshooting) → [`deploy\u002Finstall-claude-code.md`](deploy\u002Finstall-claude-code.md) §7\n\n### How it works\n\n- Reads Claude Code's per-conversation `~\u002F.claude\u002Fprojects\u002F\u003Ccwd>\u002F\u003Cuuid>.jsonl` files\n- Builds an FTS5 index at `~\u002F.claude\u002F.sr-index.db`\n- Indexer is **mtime-incremental** — typical update \u003C100ms\n- **Read-only** — never modifies Claude Code's session files\n\n### Sample output\n\n> Try: *\"What work was done on the API integration in this repo? Check session-recall-cc for recent history.\"*\n\n**`session-recall-cc list --limit 5`**\n\n| ID | Repo | Summary | Last Seen | Turns |\n|----|------|---------|-----------|-------|\n| `3b89ff09` | myorg\u002Fbackend-api | What work was done on the API integration? | 2026-05-02 | 1 |\n| `7e63b4b4` | myorg\u002Finfra | Where are the session JSON files for Claude Code located? | 2026-05-02 | 1 |\n| `78c36e1f` | myorg\u002Finfra | How do I update Claude Code? | 2026-05-02 | 2 |\n| `aed766c7` | myorg\u002Fbackend-api | Refactored auth middleware | 2026-04-23 | 1 |\n| `0f532ef0` | myorg\u002Fdotfiles | ping | 2026-04-18 | 0 |\n\n**`session-recall-cc search \"database migration\" --limit 3`**\n\n| ID | Repo | Snippet (FTS5 highlights in ⟦⟧) |\n|----|------|---------------------------------|\n| `bc112c14` | myorg\u002Fbackend-api | ⟦Database⟧ ⟦migration⟧ for user table — added indexes on email and created_at |\n| `01bf810e` | myorg\u002Finfra | Check if the staging ⟦database⟧ has pending ⟦migration⟧ scripts |\n| `3b89ff09` | myorg\u002Fbackend-api | What work was done on ⟦database⟧ ⟦migration⟧ in this repo? |\n\n### 🤖 For your AI coding agent\n\nIf you'd rather have an agent install this for you, point it at [`deploy\u002Finstall-claude-code.md`](deploy\u002Finstall-claude-code.md). The doc has YAML front-matter (`requires-user-confirmation: true`) and per-step \"agent: ask user\" prompts so a reasoning model walks you through install with confirmation at every mutating step.\n\n## Usage\n\n### Try these prompts with your agent\n\n Once wired into your agent's instruction file, session-recall runs on every prompt — giving the agent your recent files and sessions as context before it does anything else.\n\n\n```\n\"Search recent sessions about fixing the db connection bug\"\n\"Check past 5 days sessions for latest plans?\"\n\"Pick up where we left off on the API refactor\"\n\"search recent sessions for last 10 files we modified\"\n\"search sessions for the db migration bug\"\n```\n\nNo special syntax. The agent reads your session history and gets oriented in seconds instead of minutes.\n\n### How it works under the hood\n\nProgressive disclosure — most prompts never get past Tier 1.\n\n**Tier 1 — Cheap scan (~50 tokens).** Usually enough.\n\n```bash\nsession-recall files --json --limit 10\nsession-recall list --json --limit 5\n```\n\n**Tier 2 — Focused recall (~200 tokens).** When Tier 1 isn't enough.\n\n```bash\nsession-recall search \"specific term\" --json\n```\n\n**Tier 3 — Full session detail (~500 tokens).** Only when investigating something specific.\n\n```bash\nsession-recall show \u003Csession-id> --json\n```\n\n**Operational commands:**\n\n```bash\nsession-recall health          # 9-dimension health dashboard\nsession-recall schema-check    # validate DB schema after Copilot CLI upgrades\nsession-recall repos --json     # discovered repositories across providers\n```\n\n`session-recall` now supports multi-storage discovery for current Copilot CLI layouts, including session-state sources when legacy `session-store.db` is absent.\n\n## Multi-Storage Recall\n\nBy default, session-recall reads only from Copilot CLI's SQLite database. Enable file-backed providers to also recall sessions from VS Code, JetBrains, and Neovim:\n\n```bash\nexport SESSION_RECALL_ENABLE_FILE_BACKENDS=1\n```\n\n### Supported Providers\n\n| Provider | Platforms | Auto-detected paths |\n|----------|-----------|-------------------|\n| **Copilot CLI** (always on) | All | `~\u002F.copilot\u002Fsession-store.db`, `~\u002F.copilot\u002Fsession-state\u002F` |\n| **VS Code** (opt-in) | Linux, macOS, WSL | `~\u002F.config\u002FCode\u002F...`, `~\u002FLibrary\u002FApplication Support\u002FCode\u002F...`, `~\u002F.vscode-server\u002F...` |\n| **JetBrains** (opt-in) | Linux, macOS | `~\u002F.config\u002FJetBrains\u002F`, `~\u002F.config\u002Fgithub-copilot` |\n| **Neovim** (opt-in) | Linux, macOS | `~\u002F.local\u002Fshare\u002Fnvim\u002F`, `~\u002F.config\u002Fgithub-copilot` |\n\n### Lookback Defaults\n\n| Storage type | Default window | Override |\n|-------------|---------------|---------|\n| SQLite (Copilot CLI) | 30 days | `--days N` |\n| JSONL \u002F file backends | 5 days | `--days N` or `SESSION_RECALL_JSONL_DAYS=N` |\n\n### Trust Model\n\nFile-backed content is marked `_trust_level: \"untrusted_third_party\"` and wrapped in sentinel fences (`\u003C\u003CUNTRUSTED-FILE-BACKED-CONTENT>>`). CLI content is `_trust_level: \"trusted_first_party\"`. Downstream agents can use these markers to fence untrusted content.\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `SESSION_RECALL_ENABLE_FILE_BACKENDS` | `0` | Set to `1` to enable VS Code\u002FJetBrains\u002FNeovim providers |\n| `SESSION_RECALL_JSONL_DAYS` | `5` | Default lookback for file-backed providers |\n| `SESSION_RECALL_DB` | `~\u002F.copilot\u002Fsession-store.db` | Override SQLite path |\n| `SESSION_RECALL_CLI_STATE_ROOT` | `~\u002F.copilot\u002Fsession-state` | Override JSONL state dir |\n| `SESSION_RECALL_VSCODE_STORAGE` | auto-detected | Override VS Code workspace path |\n| `SESSION_RECALL_JETBRAINS_ROOT` | auto-detected | Override JetBrains path |\n| `SESSION_RECALL_NEOVIM_ROOT` | auto-detected | Override Neovim path |\n\n## Health Check\n\n`session-recall health` runs a multi-dimensional diagnostic. The core 9 dimensions check your Copilot CLI SQLite database:\n\n```\nsession-recall health\n\nDim Name                   Zone     Score  Detail\n----------------------------------------------------------------------\n 1  DB Freshness           🟢 GREEN   8.0  15.8h old\n 2  Schema Integrity       🟢 GREEN  10.0  All tables\u002Fcolumns OK\n 3  Query Latency          🟢 GREEN  10.0  1ms\n 4  Corpus Size            🟢 GREEN  10.0  399 sessions\n 5  Summary Coverage       🟢 GREEN   7.4  92% (367\u002F399)\n 6  Repo Coverage          🟢 GREEN  10.0  8 sessions for owner\u002Frepo\n 7  Concurrency            🟢 GREEN  10.0  busy=0.0%, p95=48ms\n 8  E2E Probe              🟢 GREEN  10.0  list→show OK\n 9  Progressive Disclosure  ⚪ CALIBRATING  —  Collecting baseline (n=42\u002F200)\n```\n\n### Per-Provider Health\n\nUse `--provider` to diagnose a specific backend. Each provider gets 4 sub-dimensions:\n\n| Dimension | What it checks |\n|-----------|---------------|\n| **Path Discovery** | Are the expected directories\u002FDB files present on this machine? |\n| **File Inventory** | How many session files or DB size? Is there data to read? |\n| **Recent Activity** | Sessions within the lookback window (5 days JSONL \u002F 30 days SQLite)? |\n| **Trust Model** | First-party (Copilot CLI) or third-party (VS Code\u002FJetBrains\u002FNeovim)? |\n\n```\nsession-recall health --provider cli\n\n 10 Provider:cli\n      ├─ Path Discovery     🟢 GREEN  10.0  2 path(s) found\n      ├─ File Inventory     🟢 GREEN  10.0  DB 13656064 bytes, 457 state file(s)\n      ├─ Recent Activity    🟢 GREEN  10.0  20 session(s) in last 30d\n      └─ Trust Model        🟢 GREEN  10.0  Trusted first-party; fences disabled\n```\n\n```\nsession-recall health --provider vscode\n\n 10 Provider:vscode\n      ├─ Path Discovery     🟢 GREEN  10.0  1 path(s) found\n      ├─ File Inventory     🟢 GREEN  10.0  12 file(s)\n      ├─ Recent Activity    🔴 RED     0.0  No sessions in last 5d\n      └─ Trust Model        🟢 GREEN  10.0  Untrusted third-party; output fences enabled\n```\n\nAvailable providers: `cli`, `vscode`, `jetbrains`, `neovim`, `all`\n\n**JSON output** for agent parsing:\n\n```bash\nsession-recall health --provider vscode --json\n# Returns structured JSON with providers.vscode.dimensions[] array\n```\n\n**Not enabled?** If you see `error: vscode provider is not enabled`, set the env var first:\n\n```bash\nexport SESSION_RECALL_ENABLE_FILE_BACKENDS=1\n# Or follow the full guide: deploy\u002Finstall-other-backends.md\n```\n\n## Agent Integration\n\nauto-memory works with **any agent that supports instruction files** — GitHub Copilot CLI, Claude Code, Cursor, Aider, Windsurf, and more. Installation wires session-recall into your agent's instruction file so it runs context recall automatically.\n\nSee [`deploy\u002Finstall.md`](deploy\u002Finstall.md) for setup and [`copilot-instructions-template.md`](copilot-instructions-template.md) for integration patterns.\n\nSee [`UPGRADE-COPILOT-CLI.md`](UPGRADE-COPILOT-CLI.md) for schema validation after Copilot CLI upgrades.\n\n## What This Isn't\n\n- **Not a vector database** — no embeddings, SQLite FTS5 only.\n- **Not cross-machine sync** — local only.\n- **Not a replacement for project documentation** — recalls *what you did*, not *how the system works*.\n\n## FAQ\n\n**Is it safe? Does it modify my session data?**\nNo. auto-memory is strictly read-only. It never writes to `~\u002F.copilot\u002Fsession-store.db`.\n\n**What happens when Copilot CLI updates its schema?**\nRun `session-recall schema-check` to validate. The tool fails fast on schema drift rather than returning bad data. See [UPGRADE-COPILOT-CLI.md](UPGRADE-COPILOT-CLI.md).\n\n## Roadmap\n\nSee [ROADMAP.md](ROADMAP.md).\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for setup and guidelines. Issues, PRs, and docs improvements are welcome.\n\n⭐ **If auto-memory saved you time, [star the repo](https:\u002F\u002Fgithub.com\u002Fdezgit2025\u002Fauto-memory)** — it's the best way to help others find it.\n\n🔗 **Share it:** *\"Zero-dependency CLI that gives your AI coding agent session memory. Read-only, schema-checked, ~50 tokens per prompt.\"* → [github.com\u002Fdezgit2025\u002Fauto-memory](https:\u002F\u002Fgithub.com\u002Fdezgit2025\u002Fauto-memory)\n\n## Disclaimer\n\nThis is an independent open-source project. It is **not** affiliated with, endorsed by, or supported by Microsoft, GitHub, or any other company. There is no official support — use at your own risk. Contributions and issues are welcome on GitHub.\n\n## Contributors\n\n- [@jshessen](https:\u002F\u002Fgithub.com\u002Fjshessen) — Multi-storage provider architecture ([PR #5](https:\u002F\u002Fgithub.com\u002Fdezgit2025\u002Fauto-memory\u002Fpull\u002F5))\n\n## License\n\nMIT\n","auto-memory 是一个用于增强AI编码助手记忆能力的命令行工具，通过逐步会话回忆功能帮助开发者提高效率。该项目使用Python编写，具有零依赖性的特点，能够在不增加额外负担的情况下为GitHub Copilot CLI等工具提供即时回忆支持，同时支持Claude Code等多种后端，并且具备结构化查询的能力。适用于需要频繁切换项目或任务、希望减少重复工作量以及提升开发效率的场景中。","2026-06-11 02:41:52","CREATED_QUERY"]