Metadata-Version: 2.4
Name: anima-recall-mcp
Version: 0.1.4
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: cryptography>=41
Requires-Dist: mcp[cli]<2,>=1.27
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: starlette>=0.27
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. 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

```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.
- **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`](LICENSE). Commercial, enterprise, or technology licensing: **anima.handoff@gmail.com**.

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

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