{ "markdown": "\n\n
\n\n# Recall™\n\n**A better memory server for AI agents — works for one, scales to many.**\n**Local, free, zero-config, MCP-native. Your data stays on your machine.**\n\n[![Tests](https://github.com/RecallWorks/Recall/actions/workflows/test.yml/badge.svg)](https://github.com/RecallWorks/Recall/actions/workflows/test.yml)\n[![Docker](https://github.com/RecallWorks/Recall/actions/workflows/docker.yml/badge.svg)](https://github.com/RecallWorks/Recall/actions/workflows/docker.yml)\n[![PyPI](https://img.shields.io/pypi/v/ai-recallworks?label=pypi%3A%20ai-recallworks&logo=pypi&logoColor=white)](https://pypi.org/project/ai-recallworks/)\n[![npm](https://img.shields.io/npm/v/@recallworks/recall-client?label=npm%3A%20%40recallworks%2Frecall-client&logo=npm&logoColor=white)](https://www.npmjs.com/package/@recallworks/recall-client)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue?logo=python&logoColor=white)](pyproject.toml)\n[![MCP](https://img.shields.io/badge/MCP-compatible-7c3aed)](https://modelcontextprotocol.io)\n[![Container](https://img.shields.io/badge/ghcr.io-recallworks%2Frecall-2496ED?logo=docker&logoColor=white)](https://github.com/RecallWorks/Recall/pkgs/container/recall)\n\n[**Quickstart**](#one-line-install-claude-desktop-vs-code-cursor) · [**vs. mem0/Letta/Zep**](#how-is-this-different-from-mem0--letta--zep) · [**Multi-agent**](#scaling-up-coordination-when-you-run-more-than-one-agent) · [**Recall Pro →**](#recall-open-source-vs-recall-pro-vs-hosted) · [**Book a demo**](mailto:sales@recall.works?subject=Recall%20demo)\n\n
\n\n> Without a memory server, every Claude / Copilot / Cursor conversation\n> starts cold. You re-explain the codebase, the conventions, the\n> decisions, the gotchas — every time. Recall fixes that.\n\n## Start here: what Recall does for one developer, one AI\n\nInstall it once, point your MCP client at it, and your AI now:\n\n- **Remembers across sessions** — \"what did we decide about the auth\n flow last week?\" returns the actual decision, not a hallucination\n- **Indexes your code and docs** — `index_file` + `recall` = local\n semantic RAG over your repo\n- **Cites where the answer came from** — `answer` returns text plus\n the chunks it pulled from\n- **Builds project knowledge** — every `checkpoint`, `reflect`, and\n `anti_pattern` becomes searchable later\n- **Survives restarts** — append-only artifacts on disk, vector store\n rebuildable from them\n\nOne `pip install`, one config block, done. No API key. No external\nservice. No per-token bill. MIT license. **This is what 95% of users\nwill ever use Recall for.**\n\n---\n\n## How is this different from mem0 / Letta / Zep?\n\nRecall does the same job they do — persistent memory across AI sessions,\nsemantic recall, \"remember what the user said last week.\" The difference\nis *where* and *how*:\n\n| | mem0 / Letta / Zep | Recall |\n|---|---|---|\n| **Where memory lives** | Their cloud | Your `~/.recall/` |\n| **API key required** | Yes | No |\n| **Cost** | Per-token / monthly SaaS | Free |\n| **Embeddings** | Their service | Local ONNX (offline) |\n| **Network calls** | Every recall | Zero |\n| **Air-gappable** | No | Yes |\n| **MCP-native** | Wrapper or SDK | Built on MCP |\n| **Multi-agent coordination** | None | 6 primitives |\n\nIf you're happy paying a hosted memory provider per token, those are\ngreat products and you don't need Recall. If you'd rather your AI's\nmemory live on your laptop or your own server, free and offline,\nthat's what Recall is for.\n\n---\n\n## Scaling up: coordination when you run more than one agent\n\nThe same install that gives one developer a personal AI memory also\nworks as a **shared brain** when more than one agent talks to it. Two\nCopilot windows. A planner + executor pair. Three Claude instances\ndividing up a refactor. A `pre-commit` agent and a `code-review` agent\non the same PR. They all `remember` and `recall` from the same store.\n\nThat introduces a new problem none of the hosted memory services have\neven tried to solve: **agents stepping on each other.** Agent A starts\nrefactoring `src/auth.py`. Agent B, in another window, rewrites the\nsame file with no idea A is mid-edit. Whoever saves last wins. The\nother agent's work is gone.\n\nRecall ships six MCP primitives that turn parallel agents from a\nclobber-fest into a coordinated team:\n\n| Tool | What it does |\n| ---------------------------- | ------------------------------------------------------------- |\n| `claim(resource, agent)` | Soft-lock a file/table/URL with an auto-expiring TTL |\n| `release(resource, agent)` | Drop the lock (soft-archive — audit trail survives) |\n| `who_has(resource)` | \"Is anyone editing `src/foo.py` right now?\" |\n| `claims()` | All active locks across all agents |\n| `handoff(to_agent, ...)` | Explicit work transfer with intent + files + context |\n| `pulse_others(self_agent)` | The N most recent checkpoints from agents *other than you* |\n\nClaims are advisory (like git locks) — Recall doesn't physically stop\na second agent from writing, but every well-behaved client checks\nfirst. TTLs prevent a crashed agent from freezing a resource forever.\nReleases soft-archive (per the project-wide delete=archive rule) so\nthe audit trail of who held what when survives.\n\nIf you're a single user, these tools just sit there unused. If you\never scale up to multiple agents, they're already there.\n\n```text\n ┌──────────────┐ ┌──────────────┐\n │ Agent a3f7 │ claim(file, ttl) │ Agent b1c4 │\n │ Claude #1 │ ───────────┐ ┌─────────► │ Claude #2 │\n └──────┬───────┘ ▼ │ └──────┬───────┘\n │ ┌────────┴───────┐ │\n │ remember │ Recall │ pulse │\n ├────────────► │ • shared memory│ ◄────────┤\n │ │ • claims/locks │ │\n │ handoff │ • handoffs │ handoff │\n ├────────────► │ • who_has │ ◄────────┤\n │ └────────────────┘ │\n ▼ ▼\n 22 MCP tools — Copilot, Claude, Cursor, custom\n```\n\n**22 MCP tools total** — 16 memory tools every user gets, plus the 6\ncoordination primitives that activate when you scale up.\n\n---\n\n## One-line install (Claude Desktop, VS Code, Cursor)\n\nRecall ships as a stdio MCP server. Zero config — no API keys, no Docker, no\nports. Memory lives in `~/.recall/`.\n\n```bash\npip install \"ai-recallworks[mcp]\"\n```\n\nThen add Recall to your MCP client config:\n\n**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`\non macOS, `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n\n```json\n{\n \"mcpServers\": {\n \"recall\": {\n \"command\": \"recall-mcp\"\n }\n }\n}\n```\n\n**VS Code** (`mcp.json` in your workspace or user settings):\n\n```json\n{\n \"servers\": {\n \"recall\": {\n \"command\": \"recall-mcp\"\n }\n }\n}\n```\n\nRestart the client. Your agent now has persistent memory across sessions.\nEmbeddings run fully offline (Chroma's bundled all-MiniLM-L6-v2). Upgrade\nto Ollama / OpenAI / Voyage embeddings via env vars when you want.\n\n---\n\n## Five-minute install (HTTP / multi-user / team)\n\n**1. Run the server:**\n\n```bash\ndocker run -d --name recall \\\n -p 8787:8787 \\\n -e API_KEY=changeme \\\n -v recall-data:/data \\\n ghcr.io/recallworks/recall:latest\n```\n\n**2. Talk to it — pick your stack:**\n\n```bash\n# Raw HTTP (any language)\ncurl -H \"X-API-Key: changeme\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\":\"first memory\",\"tags\":\"hello\"}' \\\n http://localhost:8787/tool/remember\n```\n\n```python\n# Python (use requests/httpx — no SDK pkg needed)\nimport requests\nh = {\"X-API-Key\": \"changeme\", \"Content-Type\": \"application/json\"}\nrequests.post(\"http://localhost:8787/tool/remember\", headers=h,\n json={\"content\": \"first memory\", \"tags\": \"hello\"})\nprint(requests.post(\"http://localhost:8787/tool/recall\", headers=h,\n json={\"query\": \"memory\"}).json()[\"result\"])\n```\n\n```ts\n// TypeScript / JavaScript (Node 18+, Bun, Deno, browser)\nnpm install @recallworks/recall-client\n\nimport { RecallClient } from \"@recallworks/recall-client\";\nconst c = new RecallClient({ baseUrl: \"http://localhost:8787\", apiKey: \"changeme\" });\nawait c.remember(\"first memory\", { tags: \"hello\" });\nconsole.log((await c.recall(\"memory\")).result);\n```\n\nFull walkthrough: [docs/quickstart.md](docs/quickstart.md).\n\n---\n\n## What you get\n\n- **13 tools** — `remember`, `recall`, `reflect`, `anti_pattern`, `checkpoint`,\n `pulse`, `session_close`, `index_file`, `reindex`, `snapshot_index`,\n `memory_stats`, `forget`, `maintenance`.\n- **Two transports** — plain HTTP (`POST /tool/{name}`) and MCP over SSE.\n Drop into Copilot, Claude Code, Cursor, or any MCP client.\n- **Bring your own models** — pluggable embedder (default / OpenAI /\n Ollama) and summarizer (noop / OpenAI / Ollama). Run fully offline,\n fully on-prem, or against your own Azure-OpenAI tenant. See\n [docs/byo-models.md](docs/byo-models.md).\n- **Durable by default** — ephemeral live store with auto-snapshot to disk;\n container restarts come up whole.\n- **Append-only artifacts** — every write also lands as a `.md` file. If the\n vector store ever burns down, `reindex` rebuilds it from the artifacts.\n- **`forget` is soft-archive** — guardrail wired into the OSS code itself, not\n bolted on as policy. Memory you delete can be recovered.\n\n---\n\n## How it's different\n\n| | Recall | Mem0 / Letta / Zep |\n|-----------------------|---------------------------------------------------|---------------------------------|\n| **License (core)** | MIT | mixed; SaaS-first |\n| **Self-host** | one `docker run` | varies, often non-trivial |\n| **BYO embedder** | default / OpenAI / Ollama (env var) | usually fixed |\n| **BYO LLM** | noop / OpenAI / Ollama (env var) | usually fixed |\n| **Storage model** | append-only artifacts + vector index, rebuildable | live DB only |\n| **`delete`** | soft-archive by design | hard delete |\n| **Tool surface** | 13 opinionated tools (memory + workflow) | embedding + retrieval primitives|\n| **MCP-native** | yes, plus plain HTTP | partial / via wrapper |\n| **Ops model** | single binary, single container | multi-service stack |\n\nIf you want a managed service, see [Recall Cloud](#recall-open-source-vs-recall-pro-vs-hosted) below. If you want a brain you fully own, this OSS core is enough.\n\n---\n\n## Repo layout\n\n| Path | What |\n|-------------------------|---------------------------------------|\n| `src/recall/` | OSS server (MIT) |\n| `src/recall/tools/` | One module per tool |\n| `src/recall/transport/` | HTTP + MCP/SSE adapters |\n| `docker/single-tenant/` | Reference Dockerfile + compose |\n| `tests/` | pytest suite (no Docker required) |\n| `docs/` | Quickstart, conventions, architecture |\n| `enterprise/` | Multi-tenant, SSO, control plane (BSL)|\n\n---\n\n## Conventions\n\nThese are the *practices* that make the tools pay off. Pick what fits.\n\n- [Cold-start ritual](docs/conventions/cold-start-ritual.md) — opening\n protocol every session should run.\n- [Branding](docs/conventions/branding.md) — signed-edit headers so you can\n trace which agent touched which file when.\n\n---\n\n## Status\n\nAlpha. The code in `src/recall/` is **extracted from a hosted production brain\nthat has served thousands of sessions**, then sanitized of org-specific\npaths, extensions, and tenant data. Expect breaking changes before 1.0; pin\nthe image tag.\n\n---\n\n## Contributing\n\nYes — please read [CONTRIBUTING.md](CONTRIBUTING.md) first. We accept bug\nfixes, new `Store` backends, doc improvements, and anti-pattern entries. We\ndon't accept architectural rewrites without prior discussion.\n\nSecurity issues: see [SECURITY.md](SECURITY.md).\n\n---\n\n## License\n\n- `src/recall/`, `clients/`, `docker/single-tenant/`, `docs/`, `examples/` — **MIT** ([LICENSE](LICENSE))\n- `enterprise/` — **BSL 1.1**, 5-seat additional-use grant, converts to MIT after 3 years ([LICENSE-COMMERCIAL.md](LICENSE-COMMERCIAL.md))\n\n---\n\n## Recall Open Source vs. Recall Pro vs. Hosted\n\n| Capability | OSS (this repo) | **Recall Pro** | **Recall Cloud** |\n|-------------------------------------|:---------------:|:--------------:|:----------------:|\n| Single-tenant Docker image | ✅ | ✅ | n/a (hosted) |\n| 13 memory tools, MCP + HTTP | ✅ | ✅ | ✅ |\n| BYO embedder + LLM | ✅ | ✅ | ✅ |\n| Append-only artifacts + auto-snapshot| ✅ | ✅ | ✅ |\n| Multi-tenant, SSO, RBAC | — | ✅ | ✅ |\n| Audit log + retention policy | — | ✅ | ✅ |\n| Cross-session entity graph | — | ✅ | ✅ |\n| PII sanitization pipeline | — | ✅ | ✅ |\n| Snapshot replication / DR | — | ✅ | ✅ |\n| Vendor support + SLA | community | business hours | 24×7 |\n| Hosted on our infra | — | — | ✅ |\n| **Pricing** | **free** | **from $99/mo per node** | **from $0.10 per 1k tools** |\n\n**Recall Pro** ships from the `enterprise/` tree under a [Business Source License](LICENSE-COMMERCIAL.md) — source-available, 5-seat free Additional Use Grant, converts to MIT after 3 years. Buy a license and the `enterprise/` modules light up alongside your OSS install.\n\n**Recall Cloud** is the hosted multi-tenant version. Same tools, no infra. Reach out for early-access pricing.\n\n➡️ Talk to sales: `sales@recall.works` · Book a 20-min walkthrough: `https://recall.works/demo`\n\n---\n\n## Vertical builds powered by Recall\n\nRecall is the engine. We ship turn-key vertical brains on top of it:\n\n- **[IceWhisperer](https://icewhisperer.ai)** — the memory + workflow brain for ICE Mortgage Technology / Encompass shops. Pre-loaded SDK index, settings recipes, plugin audits, drift detection. Pilots from $250/mo.\n\nIf you want a vertical brain for *your* industry, we'll build it. Email `partners@recall.works`.\n\n---\n\n## Maintainers\n\nReach the maintainers at `maintainers@recall.works`. Issues and PRs welcome on GitHub.\n", "bytes": 15478, "sha": "b415544ec4287d19a13a3e7fd2fc4d0b53bd8ea416accf1c846e8f63c4e22402", "repo_slug": "recallworks/recall", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_recallworks_recall_bdca64fd/readme" }