Skip to main content

🧠 recall

Your local AI brain: persistent memory + full observability for any model. Data never leaves your machine.

PyPI License: MIT Python Local-first

pipx install 'zion-recall-ai[all]'      # or: pip install 'zion-recall-ai[openai]'

AI agents have two chronic problems:

  1. They forget you. Switch models or start a new session and you re-explain everything.
  2. You can't see what they're doing. Which model? How many tokens? How much did that cost?

recall fixes both, locally, for any model. One small SQLite file holds your memories and every call's tokens/cost/latency. Switch from GPT to Claude to DeepSeek to Qwen — your memory and your bill follow you.

What you get

  • 🧠 Persistent memory across sessions and across models
  • 🔎 Hybrid retrieval — semantic + BM25 keyword search, fused (no extra deps)
  • 🤖 Auto-memory — it captures your preferences from conversation (EN + 中文)
  • 🧬 LLM extraction (opt-in) — let a model pull memories for higher recall
  • ♻️ Conflict resolution (opt-in) — ADD/UPDATE/DELETE/NOOP so facts stay current, not piled up
  • ⏳ Lifecycle — usage tracking, soft-forget, prune, recency-weighted ranking
  • 🕸️ Graph-lite — entity relationships in SQLite (no graph DB)
  • 🌊 Streaming — replies type out token-by-token
  • 📊 Observability — tokens/cost/latency per call, plus per-turn trace trees
  • 💰 Daily budget — 80% / 100% warnings, optional hard-stop
  • 🗂️ Scopes — isolate memory per project (work, home, …)
  • 🔌 22 providers — cloud, Chinese clouds, fast-inference hosts, local
  • 🔗 MCP server — any agent (Claude Desktop/Code, Cursor) reads/writes your memory
  • 📝 Prompt templates — reusable prompts with {var} substitution
  • 📦 Export / import — your memory is portable JSON
  • 🖥️ Local web dashboard — memory + cost at a glance
  • 🏠 100% local — no accounts, no servers, no telemetry
┌──────────────┐     ┌─────────────────────────────┐
│  any model   │     │  recall (local SQLite)       │
│  GPT / Claude│ ◄──►│  • memories  → auto-injected │
│  DeepSeek/Qwen│    │  • traces    → tokens & cost │
└──────────────┘     └─────────────────────────────┘
        nothing leaves your machine

Quickstart (30 seconds)

# Recommended: isolated CLI install with everything wired up
pipx install 'zion-recall-ai[all]'        # or: uv tool install 'zion-recall-ai[all]'

# Or pick what you need (base = keyword memory + tracing, no heavy deps):
pip install 'zion-recall-ai[openai]'      # GPT / DeepSeek / Qwen / OpenAI-compatible
#   pip install 'zion-recall-ai[anthropic]'   # Claude
#   pip install 'zion-recall-ai[gemini]'      # Gemini
#   pip install 'zion-recall-ai[embeddings]'  # semantic memory search (downloads a model)
#   pip install 'zion-recall-ai[dashboard]'   # web dashboard
#   pip install 'zion-recall-ai[mcp]'         # MCP server
#   pip install 'zion-recall-ai[otel]'        # OpenTelemetry export
#   pip install zion-recall-ai                # base only (keyword + tracing)

# not on PyPI yet? install straight from source:
#   pipx install 'git+https://github.com/zionLyl/recall.git#egg=zion-recall-ai[all]'
# 0. (optional) guided setup: pick a default model, detect API keys
recall init

# 1. Teach it about you (once)
recall add "I prefer concise answers with tables" --tags style
recall add "I do A-share & HK quant research"     --tags work

# 2. Chat with ANY model — it already knows you, and the call is traced
export OPENAI_API_KEY=sk-...
recall chat openai gpt-4o-mini "How should you reply to me?"
#   ↑ also auto-captures new preferences you mention

# with defaults configured, just:
recall chat "what do I work on?"

# or drop into an interactive, multi-turn chat (memory + tracing on):
recall chat

# 3. See exactly what you spent (and your budget)
recall stats
recall stats

Memories stored : 2
Model calls     : 1
Tokens          : 312 in / 88 out
Total cost      : $0.0001
Avg latency     : 740 ms

Switch model, same memory, same ledger:

export ANTHROPIC_API_KEY=sk-...
recall chat anthropic claude-3-5-sonnet "Remind me what I work on"
# → still remembers your A-share / HK quant work

Use as a library

from recall import Recall

r = Recall()
r.remember("I prefer concise answers", tags=["style"])

out = r.chat("openai", "gpt-4o-mini", "How should you reply to me?")
print(out.text)          # the model already knows your preference

print(r.stats())         # {'calls': 1, 'cost_usd': ..., ...}

Web dashboard

pip install 'zion-recall-ai[dashboard]'
recall dashboard          # → http://127.0.0.1:8745

A single local page: memory cards, cost-by-model, recent calls. No build step, no telemetry, no cloud.

Streaming

Replies stream by default — you see tokens as the model produces them, then the usual cost/latency footer.

recall chat "draft a haiku about memory"   # streams token-by-token
recall chat                                # interactive multi-turn REPL
recall chat --no-stream "..."              # wait for the full reply instead
recall config set stream false             # make non-streaming the default

In the REPL each turn keeps the in-session conversation history and your long-term memories are injected — type /exit or Ctrl-D to leave.

From the library, pass an on_token callback; you still get the full outcome:

out = r.stream("openai", "gpt-4o-mini", "tell me a joke",
               on_token=lambda t: print(t, end="", flush=True))
print(out.cost_usd, out.output_tokens)     # full accounting after streaming

Smarter memory extraction (opt-in)

By default recall captures memories with fast, free heuristics (regex cues, EN + 中文). Flip on LLM extraction to have a model read each message and pull durable first-person facts — higher recall, at the cost of one extra (cheap) call that's also traced toward your budget.

recall config set extraction_mode llm          # heuristic (default) | llm
recall config set extraction_model gpt-4o-mini # optional; defaults to chat model

If the extraction call ever fails (no key, network, bad output) recall silently falls back to the heuristic extractor, so chat never breaks.

Curate your memory

recall edit 3 "I prefer concise answers with tables"   # rewrite a memory
recall edit 3 --tags style,format                       # or just retag it

# Merge near-duplicates that pile up from auto-capture (needs embeddings)
recall dedupe --dry-run        # preview which memories would merge
recall dedupe --threshold 0.9  # keep the earliest, union tags, drop the rest
recall config set dedupe_similarity 0.95   # also suppress near-dupes on add

Editing re-embeds the memory so semantic search stays accurate. Dedupe groups memories whose embeddings are ≥ the threshold, keeps the earliest as canonical, and unions tags onto it — exact-duplicate skipping still works even without embeddings installed.

Semantic search without the model download

By default, semantic search uses a local sentence-transformers model (pip install 'zion-recall-ai[embeddings]', ~80MB on first use). If you'd rather not pull in PyTorch, point recall at any OpenAI-compatible /embeddings endpoint — e.g. a local Ollama or LM Studio you already run:

recall config set embedding_backend api
recall config set embedding_base_url http://localhost:11434/v1   # Ollama
recall config set embedding_model nomic-embed-text
# cloud endpoints: also set embedding_api_key_env to the env var holding the key

Now recall add / recall search get semantic embeddings over HTTP — no heavy local dependency. If the endpoint is unreachable, recall transparently falls back to keyword/BM25 search.

MCP server — plug recall into any agent

Expose your local memory to any MCP-aware client (Claude Desktop, Claude Code, Cursor, …) so the agent can read and write the same brain you use from the CLI.

pip install 'zion-recall-ai[mcp]'
recall mcp        # runs an MCP server over stdio

Wire it into your MCP client config:

{
  "mcpServers": {
    "recall": { "command": "recall", "args": ["mcp"] }
  }
}

Tools exposed: remember, recall_search, list_memories, forget, usage_stats. Same local SQLite store — nothing leaves your machine.

Capture your existing app's LLM calls

Already using LangChain, LlamaIndex, or the OpenAI SDK? Make recall a local sink for their calls — no server, no cloud (the local counterpart to Phoenix/Langfuse auto-instrumentation):

import recall
recall.instrument()                     # spans now land in ~/.recall/recall.db

from openinference.instrumentation.openai import OpenAIInstrumentor
OpenAIInstrumentor().instrument()       # (recall auto-enables this if installed)
# ...your normal OpenAI/LangChain code now shows up in `recall recent` / `stats`.

Needs pip install 'zion-recall-ai[otel]' plus whichever OpenInference instrumentor you use. Captured calls are tagged kind="instrumented".

Supported models (22 providers)

Mix and match across clouds, Chinese providers, fast inference hosts, and local models — your memory and cost ledger follow you everywhere.

Provider provider arg Example models API key env
OpenAI openai gpt-4o, gpt-4o-mini, gpt-4.1 OPENAI_API_KEY
Anthropic anthropic claude-3-5-sonnet, claude-3-5-haiku ANTHROPIC_API_KEY
Google Gemini gemini gemini-1.5-pro, gemini-2.0-flash GEMINI_API_KEY
DeepSeek deepseek deepseek-chat, deepseek-reasoner DEEPSEEK_API_KEY
Qwen (DashScope) qwen qwen-plus, qwen-max DASHSCOPE_API_KEY
Moonshot (Kimi) moonshot moonshot-v1-8k, moonshot-v1-32k MOONSHOT_API_KEY
Zhipu (GLM) zhipu glm-4, glm-4-flash ZHIPU_API_KEY
MiniMax minimax abab6.5s MINIMAX_API_KEY
Baichuan baichuan Baichuan4 BAICHUAN_API_KEY
01.AI (Yi) yi yi-large, yi-lightning YI_API_KEY
StepFun stepfun step-1 STEPFUN_API_KEY
Mistral mistral mistral-large, mistral-small MISTRAL_API_KEY
xAI (Grok) xai grok-2, grok-beta XAI_API_KEY
Groq groq llama-3.3-70b-versatile GROQ_API_KEY
Together together open models TOGETHER_API_KEY
Fireworks fireworks open models FIREWORKS_API_KEY
DeepInfra deepinfra open models DEEPINFRA_API_KEY
Perplexity perplexity sonar, sonar-pro PERPLEXITY_API_KEY
OpenRouter openrouter 400+ models, one key OPENROUTER_API_KEY
Ollama (local) ollama llama3, qwen2.5 —
LM Studio (local) lmstudio any loaded model —
Any OpenAI-compatible openai-compatible set --base-url RECALL_API_KEY
recall models   # list all providers + key env vars + base URLs

Most providers speak the OpenAI API, so they share one adapter — just point at the right base URL (handled automatically). Gemini has its own native adapter. Local models (Ollama / LM Studio) need no key and no cloud.

Scopes, budget & config

# Isolate memory per project
recall scope work            # switch active scope
recall add "deadline Friday" # stored in 'work'
recall scope                 # list all scopes
recall list --all            # see every scope

# Set a daily spend cap (warns at 80% and 100%)
recall config set daily_budget_usd 1.0
recall config set budget_enforce true   # hard-stop: refuse calls once the cap is hit

# Defaults so you can just `recall chat "..."`
recall config set default_provider deepseek
recall config set default_model deepseek-chat
recall config show

# Backup / move your brain
recall export my-brain.json
recall import my-brain.json

CLI reference

Command What it does
recall init Guided first-time setup
recall doctor Show which providers have keys
recall add "..." [--tags a,b] [--scope s] Store a memory
recall ingest <file.md/.txt/.pdf> Ingest a document into searchable memory
recall search "..." [--all] Semantic (or keyword) search
recall list [--all] [--at WHEN] List memories (active, or valid as-of a past time)
recall show <id> Inspect a memory + its provenance (source chat)
recall edit <id> ["new content"] [--tags ...] Edit a memory in place
recall forget <id> [--soft] Delete (or soft-forget) a memory
recall prune [--older-than DAYS] [--unused] [--all] Soft-forget stale memories
recall dedupe [--threshold 0.9] [--all] [--dry-run] Merge near-duplicate memories
recall graph [entity] [--add "s|p|o"] View / add entity relationships
recall scope [name] Switch / list scopes
recall chat [provider model] "..." [-T tmpl -V k=v] [--no-stream] Chat with memory + tracing + auto-memory
recall chat Interactive multi-turn chat (REPL)
recall stats Tokens, cost & budget overview
recall recent Recent model calls (with trace IDs)
recall trace Recent turns as call trees
recall eval <id> [--contains/--regex/--judge/--suite ...] Score a traced reply (rules / LLM judge)
recall evals [--trace id] List eval results
recall eval-suite save/list/rm Manage reusable eval suites
recall pricing [model] Show resolved per-1M-token pricing
recall benchmark Reproducible retrieval/extraction quality numbers
recall models Supported providers
recall prompt save/list/show/use/rm Manage prompt templates
recall export/import <file> Backup / restore memories
recall config show/set/path View & edit configuration
recall dashboard Launch local web UI
recall mcp Run as an MCP server (stdio) for any agent

Where is my data?

A single SQLite file at ~/.recall/recall.db (override with RECALL_HOME). That's it. No accounts, no servers, no telemetry. Back it up, sync it, delete it — it's yours.

Why local-first?

  • Privacy — your memories and prompts stay on your disk.
  • Portability — one file you can move, version, or sync yourself.
  • No lock-in — works across providers; swap models freely.

Benchmark

recall ships a reproducible, key-free quality benchmark:

recall benchmark

It seeds a fixed, hand-labeled memory set and measures retrieval quality (recall@1, recall@k, precision@k, MRR) plus heuristic-extraction fact-recall — honestly labeling whether it ran in semantic or keyword/BM25 mode. Keyword baseline: recall@1 ≈ 0.50, MRR ≈ 0.69, extraction fact-recall 1.00 with 0 false captures; installing [embeddings] (or an api backend) scores higher. Numbers are deterministic, so you can track them across changes.

Roadmap

See ROADMAP.md for how recall compares to mem0 / Letta / Zep / Langfuse / LiteLLM / simonw's llm, what it does better, and what's planned next.

  • Auto-extract memories from conversations
  • Budget alerts ("you've spent $X today")
  • Gemini + local Ollama / LM Studio adapters
  • Export / import memories
  • Memory scopes
  • Streaming chat output
  • LLM-based memory extraction (opt-in, higher recall)
  • MCP server so any agent can read/write recall memory
  • PyPI release (pip install zion-recall-ai) — automated via tag push
  • Memory editing & merge / dedupe by similarity

Contributing

Issues and PRs welcome. Run tests with:

pip install 'zion-recall-ai[dev]'
pytest

License

MIT © zionLyl

Metadata

Release files for zion-recall-ai 0.13.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zion-recall-ai 0.13.0
File Size Uploaded Provenance Actions
zion_recall_ai-0.13.0.tar.gz 84.2 kB With provenance Details for zion_recall_ai-0.13.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zion-recall-ai 0.13.0
File Interpreter ABI Platform Actions
zion_recall_ai-0.13.0-py3-none-any.whl Python 3 none any Details for zion_recall_ai-0.13.0-py3-none-any.whl

Total release size: 154.0 kB

Release files / zion_recall_ai-0.13.0.tar.gz

Download URL zion_recall_ai-0.13.0.tar.gz
Size 84.2 kB
Tags Source
SHA-256 checksum
How to use checksums
943d116fe5778a1d51b5bd46fd9cc804a30486df8d649ad51dc6e556c311e216
BLAKE2b-256 checksum
How to use checksums
a3528fa1f16be62959cd25bb2bcb201094015eb79c51ac94a117c7e4082e5292
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 31, 2026.

Transparency log

Release files / zion_recall_ai-0.13.0-py3-none-any.whl

Download URL zion_recall_ai-0.13.0-py3-none-any.whl
Size 69.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
37bd22a4da93f44a12044e08b3dddedc23392c8e6ef52022f13350cc9a71c29b
BLAKE2b-256 checksum
How to use checksums
d1c9c0065ab9b78b4b981e7f864bcefbb7ad2e345f5dc95e9d43d70986ecb31e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 31, 2026.

Transparency log

Security for zion-recall-ai 0.13.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for zion_recall_ai-0.13.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 31, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page