recall-agents 0.1.0__tar.gz

recall_agents-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.db
+*.db-*
+dist/
+build/
+*.egg-info/
+.DS_Store
+.ruff_cache/

recall_agents-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to recall are listed here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-08
+
+First public release.
+
+### Added
+
+- A local SQLite search index of the chat history from Claude Code, Codex and Cursor,
+  including older Cursor chats.
+- `recall search`, `recall show` and `recall recent` for chat history.
+- Memory notes, kept up to date by a nightly `recall dream` run. Notes cover preferences,
+  facts, decisions, lessons and open threads, and each one links to the chats it came from.
+  Notes are plain markdown with YAML frontmatter, in a git repository at `~/.agents/memory`.
+  Each run is one commit.
+- A choice of model for memory: a local model (Ollama, LM Studio or llama.cpp), your ChatGPT
+  plan through the Codex CLI, your Claude plan through Claude Code, an API key for OpenAI,
+  Anthropic or OpenRouter, or any OpenAI-compatible server.
+- API keys stored in the OS keychain, never in `config.toml`.
+- Secrets are redacted before chats are indexed.
+- Model output is checked against a JSON schema and retried with backoff. Every model call is
+  logged. Runs are capped with `--max-minutes` and `--max-calls`.
+- Open threads expire after 14 days, and weak single-source notes fade after six months.
+- An MCP server (`recall serve`) with six read-only tools: `search_chats`, `read_chat`,
+  `recent_chats`, `memory_search`, `read_note` and `project_memory`.
+- A `/recall` skill, and a Claude Code session-start hook that loads your working preferences
+  and the current project's memory.
+- `recall install` and `recall uninstall` for the MCP server, skill and hook. Each agent
+  config file is backed up before it changes.
+- A nightly memory schedule through launchd on macOS or systemd on Linux (`recall schedule`).
+- `recall setup`, a guided first run, and `recall model` to change the model later.
+- `recall eval search` and `recall eval memory` to measure search and extraction quality.
+
+[Unreleased]: https://github.com/alirng/recall/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/alirng/recall/releases/tag/v0.1.0

recall_agents-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali Rangwala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

recall_agents-0.1.0/PKG-INFO

@@ -0,0 +1,288 @@
+Metadata-Version: 2.5
+Name: recall-agents
+Version: 0.1.0
+Summary: One searchable memory of your Claude Code, Codex and Cursor chats, exposed to every agent over MCP.
+Project-URL: Homepage, https://github.com/alirng/recall
+Project-URL: Issues, https://github.com/alirng/recall/issues
+Project-URL: Changelog, https://github.com/alirng/recall/blob/main/CHANGELOG.md
+Author: Ali Rangwala
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,chat-history,claude-code,cli,codex,cursor,llm,mcp,memory,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pyyaml>=6
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=1; extra == 'anthropic'
+Description-Content-Type: text/markdown
+
+# recall
+
+**One memory for all your coding agents.**
+
+[![CI](https://github.com/alirng/recall/actions/workflows/ci.yml/badge.svg)](https://github.com/alirng/recall/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)
+![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)
+
+Your coding agents forget everything between sessions, and none of them knows what you told
+the others. recall reads the chat history that Claude Code, Codex and Cursor already keep on
+your machine, and gives every agent two things:
+
+- **Search across every chat.** "Find the Cursor chat where we planned the auth refactor"
+  works in any agent, whichever tool the chat happened in.
+- **Memory.** A small set of plain markdown notes, rewritten nightly: how you like to work,
+  what each project needs, what was decided, what went wrong, and what is still open. Each
+  note links to the chats it came from.
+
+It runs on your machine. You choose the model that writes the memories: a local one that
+keeps everything private, your ChatGPT or Claude subscription, or your own API key or server.
+
+```text
+you   › what did we decide about retries in the payments service?
+agent › Searching your past chats… In "Payment webhook retries" (Codex, 2 Oct) you settled
+        on exponential backoff capped at 5 attempts, and a dead-letter queue for the rest.
+        Memory also notes: "Never retry card captures; they are not idempotent."
+```
+
+## Contents
+
+[Install](#install) · [Quick start](#quick-start) · [Choosing a model](#choosing-a-model) ·
+[How agents use it](#how-agents-use-it) · [How it works](#how-it-works) ·
+[Memory notes](#memory-notes) · [Commands](#commands) · [FAQ](#faq) ·
+[Contributing](#contributing)
+
+## Install
+
+Requirements: macOS or Linux, Python 3.11+, and at least one of Claude Code, Codex or Cursor.
+
+```bash
+uv tool install git+https://github.com/alirng/recall
+# or: pipx install git+https://github.com/alirng/recall
+```
+
+A PyPI release (`recall-agents`) is coming; the command is `recall` either way.
+
+## Quick start
+
+```bash
+recall setup
+```
+
+Setup asks a few questions and does the rest:
+
+```text
+1. Agents      finds Claude Code, Codex and Cursor; import from all of them or some
+2. Model       picks who writes your memories, then tests it with a live call
+3. Index       reads your chat history into a local search index
+4. Connect     adds the MCP tools, the /recall skill and a Claude Code session hook
+5. Schedule    updates memory nightly (launchd on macOS, systemd on Linux)
+6. First run   starts in the background, newest chats first
+```
+
+Then ask any agent about an earlier conversation, or just start working: Claude Code opens
+each session with your preferences and the current project's notes already loaded.
+
+## Choosing a model
+
+recall distils chats with a language model. Pick the one that fits your privacy and budget:
+
+| Option | What it uses | Where chat excerpts go |
+| --- | --- | --- |
+| **Local model** | Ollama, LM Studio or llama.cpp on this machine | nowhere: they stay on this machine |
+| **ChatGPT** | your ChatGPT plan, through the Codex CLI | OpenAI, under your plan's data terms |
+| **Claude** | your Claude plan, through Claude Code | Anthropic, under your plan's data terms |
+| **API key** | OpenAI, Anthropic or OpenRouter | that provider, billed to your key |
+| **Your server** | any OpenAI-compatible endpoint, such as vLLM or Ollama on another box | your server |
+
+Change it any time with `recall model`. The choice is saved in `~/.agents/recall/config.toml`:
+
+```toml
+[model]
+provider = "local"                     # local | chatgpt | claude | openai | anthropic | openrouter | custom
+name = "qwen3:4b"
+server = "ollama"                      # local only
+base_url = "http://localhost:11434"    # local and custom
+api_key = "keychain"                   # env:NAME, keychain or file; never the key itself
+```
+
+Whichever you pick, every call is validated against a strict JSON schema, retried with
+backoff, cached, logged, and capped by time and call budgets. recall's own calls never show
+up in your chat history, and the subscription CLIs run with your MCP servers, hooks and
+plugins switched off.
+
+For a local model, smaller is kinder to your laptop: a 4B model suits 16 GB of memory.
+
+## How agents use it
+
+| Agent | History import | MCP tools | `/recall` skill | Memory at session start |
+| --- | --- | --- | --- | --- |
+| Claude Code | yes | yes | yes | automatic, via a session-start hook |
+| Codex | yes | yes | yes | on request, via the `project_memory` tool |
+| Cursor | yes, including older chats | yes | yes | on request, via the `project_memory` tool |
+
+- **Automatic:** the session-start hook loads your working preferences and the current
+  project's notes, capped at 6,000 characters.
+- **On demand:** six read-only MCP tools: `search_chats`, `read_chat`, `recent_chats`,
+  `memory_search`, `read_note` and `project_memory`.
+- **Explicit:** type `/recall what did we decide about auth` in any agent with skills.
+
+Agents treat notes and transcripts as background, not instructions: the current request and
+the code win when they disagree.
+
+## How it works
+
+```text
+ Claude Code ─┐                                    ┌─ dream (nightly) ──────────────────────────┐
+ Codex ───────┼─ parse & clean ─ redact ─ SQLite ──┤  digest → extract → consolidate → notes     │
+ Cursor ──────┘                          (FTS5)    │          (batched)   (per project)  (git)   │
+                                                   └────────────────────────────────────────────┘
+               ↓ search_chats, read_chat                      ↓ MEMORY.md indexes
+          MCP server · /recall skill · CLI            session-start hook · memory_search
+```
+
+1. **Index.** Each agent's history is parsed into your turns and the agent's turns. Tool
+   output and text the tools inject (system reminders, plan-mode boilerplate) are dropped,
+   and secrets are redacted before anything is stored. Headless runs and subagents stay
+   searchable but are never mined for memory. Clones and worktrees of one repo share a
+   project, keyed on the git remote.
+2. **Digest.** Each chat shrinks to your words plus the start and end of each agent reply,
+   which is where agents say what they will do and what they did.
+3. **Extract.** The model proposes candidate memories (`preference`, `fact`, `decision`,
+   `lesson`, `open`), each with a supporting quote. A quote that can't be found in the chat
+   demotes the candidate to low confidence.
+4. **Consolidate.** Per project, oldest first, candidates are folded into notes: create,
+   update, supersede (newer facts win) or discard. Every operation is validated before a
+   file changes. Open threads expire after 14 days.
+5. **Commit.** The `MEMORY.md` indexes are rebuilt, and the run becomes one git commit in
+   `~/.agents/memory`.
+
+Each step resumes where the last run stopped, so a crash or a spent budget only delays the
+rest until the next night.
+
+## Memory notes
+
+```text
+~/.agents/memory/
+  MEMORY.md                      how you work, and your projects
+  global/<note>.md               cross-project preferences
+  projects/<repo>/MEMORY.md      what an agent loads when it starts in that repo
+  projects/<repo>/<note>.md      facts, decisions, lessons, open threads
+  archive/                       superseded and expired notes
+```
+
+A note is plain markdown with a little YAML:
+
+```markdown
+---
+id: run-migrations-through-make-3f2a
+type: lesson
+scope: project
+confidence: high
+last_seen: '2026-09-30'
+sources: [codex:0192f…, claude:7c41e…]
+---
+Run database migrations with `make migrate`, never by hand: the Makefile also seeds
+the audit tables. Why: two hand-run migrations left staging without audit rows.
+```
+
+The files are the source of truth. Edit them, and recall keeps your edits; delete one, and
+it is never learned again. The folder is a git repository, so `git log` shows what each
+night changed and `git revert` undoes it. It also opens as an Obsidian vault, though nothing
+requires Obsidian. Why markdown rather than a vector or graph store:
+[docs/research/agent-memory-prior-art.md](docs/research/agent-memory-prior-art.md).
+
+## Commands
+
+| Command | Does |
+| --- | --- |
+| `recall setup` | the guided first run |
+| `recall model [--show]` | choose, or show, the model that writes memories |
+| `recall search <words>` · `show <id>` · `recent` | chat history |
+| `recall dream [--max-minutes N] [--max-calls N]` | update memory now |
+| `recall memory [search <words> \| show <id>]` | browse notes |
+| `recall context [--cwd DIR]` | print the memory block an agent gets at session start |
+| `recall install` · `uninstall [--only mcp,skill,hook]` | connect to agents (every config file is backed up first) |
+| `recall schedule enable \| disable \| status` | the nightly run |
+| `recall eval search \| memory` | quality checks |
+
+Environment: `RECALL_HOME` moves the index, config and logs (default `~/.agents/recall`);
+`RECALL_MEMORY` moves the notes (default `~/.agents/memory`).
+
+### Uninstall
+
+```bash
+recall uninstall && recall schedule disable
+uv tool uninstall recall-agents
+rm -rf ~/.agents/recall          # the index, config and logs
+# ~/.agents/memory holds your notes; keep it or delete it
+```
+
+## FAQ
+
+**Does recall send my chats anywhere?**
+Only to the model you choose, and only digests of chats, after secrets are redacted. With a
+local model nothing leaves your machine. recall has no telemetry. See [SECURITY.md](SECURITY.md).
+
+**What does it cost?**
+With a local model, nothing but electricity. With a subscription it uses your plan's
+allowance; the nightly run is capped (80 model calls by default), and a first backfill of a
+few thousand chats spreads across several nights. With an API key, a small model such as
+Claude Haiku costs cents per night for typical use.
+
+**How is this different from Claude Code's or Codex's own memory?**
+Each tool's memory only knows that tool's chats and lives in its own format. recall spans
+all of them, keeps memory as plain files you own, and links every note to its source chats.
+
+**Can I use it with only one agent?**
+Yes. Search and memory work with any one of Claude Code, Codex or Cursor.
+
+**Windows?**
+Not yet. The chat parsers are portable, but file locking, the nightly scheduler and key
+storage need Windows equivalents. Contributions welcome.
+
+**Will memory pick up something wrong?**
+Sometimes. Every note carries its sources and a confidence level, newer chats supersede
+older notes, and you can edit or delete any note. Treat memory as a well-informed colleague's
+notes, not as ground truth.
+
+## Quality
+
+There are no unit tests by design. recall is checked with evals that drive the real
+pipeline, plus an end-to-end smoke test in CI:
+
+```bash
+recall eval search                 # hand-written and auto-generated "find that chat" queries
+recall eval memory --fresh         # extraction against hand-labelled chats; average several runs
+```
+
+On one developer's 2,700 chats, search finds the intended chat first 80–100% of the time and
+in the top five 97–100% of the time. Memory extraction quality depends on the model. Small
+hosted models find roughly half to three quarters of hand-labelled memories, with very little
+junk. Single runs vary by ±12 points, so compare averages.
+
+## Contributing
+
+Contributions are welcome, especially new agent sources (opencode, Gemini CLI, Copilot CLI,
+Goose and more are mapped out in
+[docs/research/agent-storage-and-integration.md](docs/research/agent-storage-and-integration.md))
+and new model providers. See [CONTRIBUTING.md](CONTRIBUTING.md) to get set up, and
+[SECURITY.md](SECURITY.md) to report a vulnerability privately. Please never include real
+chat content in issues or pull requests.
+
+**Roadmap:** more agents and chat-export imports, a Codex session-start hook, a "remember
+this" write path from any agent, usefulness evals that replay tasks with and without memory,
+and a Claude Code plugin package.
+
+## License
+
+[MIT](LICENSE)

recall_agents-0.1.0/README.md

@@ -0,0 +1,261 @@
+# recall
+
+**One memory for all your coding agents.**
+
+[![CI](https://github.com/alirng/recall/actions/workflows/ci.yml/badge.svg)](https://github.com/alirng/recall/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)
+![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)
+
+Your coding agents forget everything between sessions, and none of them knows what you told
+the others. recall reads the chat history that Claude Code, Codex and Cursor already keep on
+your machine, and gives every agent two things:
+
+- **Search across every chat.** "Find the Cursor chat where we planned the auth refactor"
+  works in any agent, whichever tool the chat happened in.
+- **Memory.** A small set of plain markdown notes, rewritten nightly: how you like to work,
+  what each project needs, what was decided, what went wrong, and what is still open. Each
+  note links to the chats it came from.
+
+It runs on your machine. You choose the model that writes the memories: a local one that
+keeps everything private, your ChatGPT or Claude subscription, or your own API key or server.
+
+```text
+you   › what did we decide about retries in the payments service?
+agent › Searching your past chats… In "Payment webhook retries" (Codex, 2 Oct) you settled
+        on exponential backoff capped at 5 attempts, and a dead-letter queue for the rest.
+        Memory also notes: "Never retry card captures; they are not idempotent."
+```
+
+## Contents
+
+[Install](#install) · [Quick start](#quick-start) · [Choosing a model](#choosing-a-model) ·
+[How agents use it](#how-agents-use-it) · [How it works](#how-it-works) ·
+[Memory notes](#memory-notes) · [Commands](#commands) · [FAQ](#faq) ·
+[Contributing](#contributing)
+
+## Install
+
+Requirements: macOS or Linux, Python 3.11+, and at least one of Claude Code, Codex or Cursor.
+
+```bash
+uv tool install git+https://github.com/alirng/recall
+# or: pipx install git+https://github.com/alirng/recall
+```
+
+A PyPI release (`recall-agents`) is coming; the command is `recall` either way.
+
+## Quick start
+
+```bash
+recall setup
+```
+
+Setup asks a few questions and does the rest:
+
+```text
+1. Agents      finds Claude Code, Codex and Cursor; import from all of them or some
+2. Model       picks who writes your memories, then tests it with a live call
+3. Index       reads your chat history into a local search index
+4. Connect     adds the MCP tools, the /recall skill and a Claude Code session hook
+5. Schedule    updates memory nightly (launchd on macOS, systemd on Linux)
+6. First run   starts in the background, newest chats first
+```
+
+Then ask any agent about an earlier conversation, or just start working: Claude Code opens
+each session with your preferences and the current project's notes already loaded.
+
+## Choosing a model
+
+recall distils chats with a language model. Pick the one that fits your privacy and budget:
+
+| Option | What it uses | Where chat excerpts go |
+| --- | --- | --- |
+| **Local model** | Ollama, LM Studio or llama.cpp on this machine | nowhere: they stay on this machine |
+| **ChatGPT** | your ChatGPT plan, through the Codex CLI | OpenAI, under your plan's data terms |
+| **Claude** | your Claude plan, through Claude Code | Anthropic, under your plan's data terms |
+| **API key** | OpenAI, Anthropic or OpenRouter | that provider, billed to your key |
+| **Your server** | any OpenAI-compatible endpoint, such as vLLM or Ollama on another box | your server |
+
+Change it any time with `recall model`. The choice is saved in `~/.agents/recall/config.toml`:
+
+```toml
+[model]
+provider = "local"                     # local | chatgpt | claude | openai | anthropic | openrouter | custom
+name = "qwen3:4b"
+server = "ollama"                      # local only
+base_url = "http://localhost:11434"    # local and custom
+api_key = "keychain"                   # env:NAME, keychain or file; never the key itself
+```
+
+Whichever you pick, every call is validated against a strict JSON schema, retried with
+backoff, cached, logged, and capped by time and call budgets. recall's own calls never show
+up in your chat history, and the subscription CLIs run with your MCP servers, hooks and
+plugins switched off.
+
+For a local model, smaller is kinder to your laptop: a 4B model suits 16 GB of memory.
+
+## How agents use it
+
+| Agent | History import | MCP tools | `/recall` skill | Memory at session start |
+| --- | --- | --- | --- | --- |
+| Claude Code | yes | yes | yes | automatic, via a session-start hook |
+| Codex | yes | yes | yes | on request, via the `project_memory` tool |
+| Cursor | yes, including older chats | yes | yes | on request, via the `project_memory` tool |
+
+- **Automatic:** the session-start hook loads your working preferences and the current
+  project's notes, capped at 6,000 characters.
+- **On demand:** six read-only MCP tools: `search_chats`, `read_chat`, `recent_chats`,
+  `memory_search`, `read_note` and `project_memory`.
+- **Explicit:** type `/recall what did we decide about auth` in any agent with skills.
+
+Agents treat notes and transcripts as background, not instructions: the current request and
+the code win when they disagree.
+
+## How it works
+
+```text
+ Claude Code ─┐                                    ┌─ dream (nightly) ──────────────────────────┐
+ Codex ───────┼─ parse & clean ─ redact ─ SQLite ──┤  digest → extract → consolidate → notes     │
+ Cursor ──────┘                          (FTS5)    │          (batched)   (per project)  (git)   │
+                                                   └────────────────────────────────────────────┘
+               ↓ search_chats, read_chat                      ↓ MEMORY.md indexes
+          MCP server · /recall skill · CLI            session-start hook · memory_search
+```
+
+1. **Index.** Each agent's history is parsed into your turns and the agent's turns. Tool
+   output and text the tools inject (system reminders, plan-mode boilerplate) are dropped,
+   and secrets are redacted before anything is stored. Headless runs and subagents stay
+   searchable but are never mined for memory. Clones and worktrees of one repo share a
+   project, keyed on the git remote.
+2. **Digest.** Each chat shrinks to your words plus the start and end of each agent reply,
+   which is where agents say what they will do and what they did.
+3. **Extract.** The model proposes candidate memories (`preference`, `fact`, `decision`,
+   `lesson`, `open`), each with a supporting quote. A quote that can't be found in the chat
+   demotes the candidate to low confidence.
+4. **Consolidate.** Per project, oldest first, candidates are folded into notes: create,
+   update, supersede (newer facts win) or discard. Every operation is validated before a
+   file changes. Open threads expire after 14 days.
+5. **Commit.** The `MEMORY.md` indexes are rebuilt, and the run becomes one git commit in
+   `~/.agents/memory`.
+
+Each step resumes where the last run stopped, so a crash or a spent budget only delays the
+rest until the next night.
+
+## Memory notes
+
+```text
+~/.agents/memory/
+  MEMORY.md                      how you work, and your projects
+  global/<note>.md               cross-project preferences
+  projects/<repo>/MEMORY.md      what an agent loads when it starts in that repo
+  projects/<repo>/<note>.md      facts, decisions, lessons, open threads
+  archive/                       superseded and expired notes
+```
+
+A note is plain markdown with a little YAML:
+
+```markdown
+---
+id: run-migrations-through-make-3f2a
+type: lesson
+scope: project
+confidence: high
+last_seen: '2026-09-30'
+sources: [codex:0192f…, claude:7c41e…]
+---
+Run database migrations with `make migrate`, never by hand: the Makefile also seeds
+the audit tables. Why: two hand-run migrations left staging without audit rows.
+```
+
+The files are the source of truth. Edit them, and recall keeps your edits; delete one, and
+it is never learned again. The folder is a git repository, so `git log` shows what each
+night changed and `git revert` undoes it. It also opens as an Obsidian vault, though nothing
+requires Obsidian. Why markdown rather than a vector or graph store:
+[docs/research/agent-memory-prior-art.md](docs/research/agent-memory-prior-art.md).
+
+## Commands
+
+| Command | Does |
+| --- | --- |
+| `recall setup` | the guided first run |
+| `recall model [--show]` | choose, or show, the model that writes memories |
+| `recall search <words>` · `show <id>` · `recent` | chat history |
+| `recall dream [--max-minutes N] [--max-calls N]` | update memory now |
+| `recall memory [search <words> \| show <id>]` | browse notes |
+| `recall context [--cwd DIR]` | print the memory block an agent gets at session start |
+| `recall install` · `uninstall [--only mcp,skill,hook]` | connect to agents (every config file is backed up first) |
+| `recall schedule enable \| disable \| status` | the nightly run |
+| `recall eval search \| memory` | quality checks |
+
+Environment: `RECALL_HOME` moves the index, config and logs (default `~/.agents/recall`);
+`RECALL_MEMORY` moves the notes (default `~/.agents/memory`).
+
+### Uninstall
+
+```bash
+recall uninstall && recall schedule disable
+uv tool uninstall recall-agents
+rm -rf ~/.agents/recall          # the index, config and logs
+# ~/.agents/memory holds your notes; keep it or delete it
+```
+
+## FAQ
+
+**Does recall send my chats anywhere?**
+Only to the model you choose, and only digests of chats, after secrets are redacted. With a
+local model nothing leaves your machine. recall has no telemetry. See [SECURITY.md](SECURITY.md).
+
+**What does it cost?**
+With a local model, nothing but electricity. With a subscription it uses your plan's
+allowance; the nightly run is capped (80 model calls by default), and a first backfill of a
+few thousand chats spreads across several nights. With an API key, a small model such as
+Claude Haiku costs cents per night for typical use.
+
+**How is this different from Claude Code's or Codex's own memory?**
+Each tool's memory only knows that tool's chats and lives in its own format. recall spans
+all of them, keeps memory as plain files you own, and links every note to its source chats.
+
+**Can I use it with only one agent?**
+Yes. Search and memory work with any one of Claude Code, Codex or Cursor.
+
+**Windows?**
+Not yet. The chat parsers are portable, but file locking, the nightly scheduler and key
+storage need Windows equivalents. Contributions welcome.
+
+**Will memory pick up something wrong?**
+Sometimes. Every note carries its sources and a confidence level, newer chats supersede
+older notes, and you can edit or delete any note. Treat memory as a well-informed colleague's
+notes, not as ground truth.
+
+## Quality
+
+There are no unit tests by design. recall is checked with evals that drive the real
+pipeline, plus an end-to-end smoke test in CI:
+
+```bash
+recall eval search                 # hand-written and auto-generated "find that chat" queries
+recall eval memory --fresh         # extraction against hand-labelled chats; average several runs
+```
+
+On one developer's 2,700 chats, search finds the intended chat first 80–100% of the time and
+in the top five 97–100% of the time. Memory extraction quality depends on the model. Small
+hosted models find roughly half to three quarters of hand-labelled memories, with very little
+junk. Single runs vary by ±12 points, so compare averages.
+
+## Contributing
+
+Contributions are welcome, especially new agent sources (opencode, Gemini CLI, Copilot CLI,
+Goose and more are mapped out in
+[docs/research/agent-storage-and-integration.md](docs/research/agent-storage-and-integration.md))
+and new model providers. See [CONTRIBUTING.md](CONTRIBUTING.md) to get set up, and
+[SECURITY.md](SECURITY.md) to report a vulnerability privately. Please never include real
+chat content in issues or pull requests.
+
+**Roadmap:** more agents and chat-export imports, a Codex session-start hook, a "remember
+this" write path from any agent, usefulness evals that replay tasks with and without memory,
+and a Claude Code plugin package.
+
+## License
+
+[MIT](LICENSE)

recall_agents-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "recall-agents"
+version = "0.1.0"
+description = "One searchable memory of your Claude Code, Codex and Cursor chats, exposed to every agent over MCP."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ali Rangwala" }]
+keywords = ["mcp", "model-context-protocol", "claude-code", "codex", "cursor", "llm", "agents", "memory", "chat-history", "cli"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Topic :: Software Development",
+]
+dependencies = ["mcp>=2.3,<3", "pyyaml>=6", "jsonschema>=4.20"]
+
+[project.urls]
+Homepage = "https://github.com/alirng/recall"
+Issues = "https://github.com/alirng/recall/issues"
+Changelog = "https://github.com/alirng/recall/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=1"]
+
+[project.scripts]
+recall = "recall.cli:main"
+
+[build-system]
+requires = ["hatchling>=1.27"]  # PEP 639 license metadata
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/recall"]
+
+[tool.hatch.build.targets.sdist]
+# The published source holds the package and its license; research notes and agent
+# instructions stay in the repository.
+include = ["src/recall", "README.md", "LICENSE", "CHANGELOG.md", "pyproject.toml"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+ignore = [
+  "RUF001", "RUF002", "RUF003",  # typographic characters in prose are intentional
+  "SIM905",                      # word lists read better as one split() string
+]