anima-recall-mcp 0.1.4

Local-first decision memory and consistency review MCP server.

ANIMA Recall

Your AI forgets every decision you make. This one remembers — and flags it for review when your next choice looks like it contradicts a past one.

ANIMA Recall is a local-first MCP server that gives any MCP host (Claude Desktop, and other MCP clients) a durable memory of your decisions, principles, and promises — and reviews new choices against them.

You've done this: told your assistant "we never send raw customer data to third parties," and three sessions later it happily proposes exactly that, because the context window forgot. ANIMA Recall stores that decision once and flags it for your review the next time a related choice comes up.

you   → remember: "avoid sending customer data to external services" (a decision)
...many sessions later...
you   → I'm about to push analytics events to a third-party API. Any conflict?
ANIMA → ⚠ potential conflict on topic "customer data": a past decision says
         avoid, this proposes require.

It stays out of your way when there's no conflict, and it only speaks up on the topic you actually decided about — not on every memory that happens to share a word.

Why it's different

• Local-first. Your memories live in a SQLite file on your machine. The content and the comparison logic never leave it. There is no memory cloud to breach.
• No model calls, ever. Recall and contradiction-review are deterministic and offline — same input, same answer, zero API cost, nothing sent anywhere.
• It refuses to store secrets. Try to save an API key, token, or private key as a memory and the call is rejected before it touches disk. It is a safety net against an accidental paste, not a boundary: it matches known credential shapes (measured 94.7% across 15 issuer formats, 0 false alarms on 150 ordinary sentences), and a deliberately mangled secret can still get through.
• Honest by design. anima_compare_choice flags choices for your review — it matches on keywords, common synonyms, and direction, not meaning. It catches contradictions that share wording (and their synonyms); it can miss one phrased in entirely different words. Treat it as a prompt to look again, not a guarantee — it surfaces what's worth a second look, and you decide.

Tools

Tool	Purpose	Effect
anima_remember	Store an explicit decision, principle, or promise	Writes
anima_recall_memories	Find relevant past memories	Reads
anima_compare_choice	Flag possible conflicts with past decisions	Reads
anima_recent_memories	List recent memories	Reads
anima_reflect	Review recurring patterns, conflicts, and principle candidates	Preview by default — paid tier
anima_forget	Delete one explicitly confirmed memory	Deletes

anima_reflect never writes a standing principle into your store unless you explicitly pass promote=true. By default it only shows you what it would promote — your memory is never edited behind your back.

Install

python -m pip install anima-recall-mcp

Run it (streamable-HTTP MCP server):

# a stable local secret so owner identity is consistent across restarts
export ANIMA_RECALL_OWNER_PEPPER="replace-with-at-least-32-random-bytes"
export ANIMA_RECALL_DB="$HOME/.anima/anima_recall.db"
anima-recall-mcp

• MCP endpoint: http://127.0.0.1:8000/mcp
• Health: http://127.0.0.1:8000/health
• Privacy notice: http://127.0.0.1:8000/privacy

Point your MCP host at the endpoint above. See docs/CONNECT.md for host-specific wiring and docs/ARCHITECTURE.md for how the pieces fit.

Privacy and deployment

• No name or email is ever required in tool input; owners are identified by a local salted hash.
• Memory content is stored only in your configured local SQLite database.
• Set ANIMA_RECALL_OWNER_PEPPER. It is not enforced: with it unset the server falls back to a built-in development value, which makes owner hashes predictable. The server warns about this only in multi-tenant mode.
• Multi-tenant gateways must set ANIMA_RECALL_GATEWAY_SECRET and authenticate requests with the documented gateway header; single-user local runs need nothing extra.
• Multi-tenant gateways should also pin ANIMA_RECALL_IDENTITY_HEADER to the single header they verify, and strip client-supplied identity headers. Without it, a request carrying two different identity headers is refused rather than guessed at.
• Deletion is a real DELETE with secure_delete enabled, so the row's bytes are overwritten in the database file rather than left in a freed page. Backups you made earlier still contain it.
• Back up the database file before upgrades.

License

Personal & non-commercial use. See LICENSE. Commercial, enterprise, or technology licensing: [e-mail].

The five memory tools — anima_remember, anima_recall_memories, anima_compare_choice, anima_recent_memories, anima_forget — need no license key. anima_reflect requires a plus key in ANIMA_RECALL_LICENSE or ~/.animarecall/license; without one it returns an error telling you so.

Development

export PYTHONPATH=src
python -m pytest -q      # full suite
python -m build