Metadata-Version: 2.4
Name: anima-recall-mcp
Version: 0.1.3
Summary: Local-first decision memory and consistency review MCP server.
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: aiosqlite<1,>=0.21
Requires-Dist: mcp[cli]<2,>=1.27
Requires-Dist: pydantic<3,>=2.10
Provides-Extra: dev
Requires-Dist: pytest-asyncio<1,>=0.25; extra == 'dev'
Requires-Dist: pytest<9,>=8.3; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://modelcontextprotocol.io) 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.
- **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 |
| `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

```bash
python -m pip install anima-recall-mcp
```

Run it (streamable-HTTP MCP server):

```bash
# 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`](docs/CONNECT.md) for host-specific wiring and [`docs/ARCHITECTURE.md`](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.
- A high-entropy `ANIMA_RECALL_OWNER_PEPPER` is required.
- Multi-tenant gateways must set `ANIMA_RECALL_GATEWAY_SECRET` and authenticate requests with the documented gateway header; single-user local runs need nothing extra.
- Back up the database file before upgrades.

## License

Personal & non-commercial use. See [`LICENSE`](LICENSE). Commercial, enterprise, or technology licensing: **anima.handoff@gmail.com**.

Early access is free through **2026-09-30 (UTC)**.

## Development

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