Content
<div align="center">
[](README.md)
[](README.zh-CN.md)
[](README.ja.md)
</div>
# mory-memory · MCP-native long-term memory for AI companions
> 给 AI 一层跨会话的长期记忆 · Long-term memory any MCP client can plug into · MCPで繋ぐAIの長期記憶
---
<div align="center">
### ☁️ Don't want to self-host? Use the hosted **[mory](https://usemory.com)** cloud memory.
**Claude.ai and the ChatGPT app have nowhere to keep context between sessions.**
[**mory**](https://usemory.com) runs this exact engine as a **managed cloud MCP server** —
**no deployment, no database, no ops.** Connect your AI once and it remembers you across
every session.
#### → [**Get your cloud memory at usemory.com**](https://usemory.com) ←
</div>
---
[](https://github.com/blanchexxxxx/mory-memory/actions/workflows/tests.yml)
[](./LICENSE)
A memory engine that gives an AI assistant a durable sense of **who you are** and
**what has happened**, across sessions — exposed entirely through the
[Model Context Protocol](https://modelcontextprotocol.io) so any MCP client
(Claude Desktop, Claude.ai, Cursor, Cline, …) can read and write it.
Three layers, each with its own update cadence, retrieval mode, and lifecycle —
so core identity isn't decayed away alongside a throwaway snippet:
- **Identity** (`cards`) — who the user is: preferences, state, relationships. Versioned.
- **Event** (`memories`) — what happened / what's unresolved: affect coordinates
(valence/arousal), importance, and time-decay, recalled semantically via **pgvector**.
- **Ephemeral** (`conversations`, `chat_messages`, summary DAG) — recent / right-now.
Full write-up: **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**.
How this repo is built with a fleet of AI agents: **[docs/AI_WORKFLOW.md](docs/AI_WORKFLOW.md)**.
## Why
Chat assistants forget everything between sessions. Bolting a vector store on top gets
you *retrieval*, but not *memory*: no notion of identity vs. events vs. transient
chatter, no emotional weighting, no forgetting. `mory-memory` models those distinctions
as first-class structure and serves them over MCP, so the memory layer is decoupled
from any particular chat UI or model.
## MCP tools
**Memory** — `save_memory` · `get_memories` · `search_memories` · `get_memory_detail` ·
`update_memory` · `delete_memory` · `restore_memory` · `batch_delete_memories` ·
`surface_memories`
**Identity cards** — `get_cards` · `update_card` · `get_card_diff` · `get_card_history`
**Conversations** — `save_conversation` · `get_conversations` · `get_resume_context` ·
`get_archive`
**Diary & comments** — `write_diary` · `get_diary` · `post_comment` · `get_comments`
**Tasks** — `save_task` · `get_tasks` · `update_task` · `complete_task` · `delete_task`
**Vault (summary DAG)** — `search_vault` · `expand_vault` · `recall_chat`
## Self-host quickstart
> Prefer zero setup? Use the hosted cloud at **[usemory.com](https://usemory.com)** instead.
```bash
git clone https://github.com/blanchexxxxx/mory-memory
cd mory-memory
cp .env.example .env # add an OPENAI_API_KEY for embeddings (optional)
docker compose up --build # Postgres 16 + pgvector and the MCP server
```
Mint a bearer token and point an MCP client at the server:
```bash
docker compose exec server python -m scripts.create_token
# → bearer : mbr_xxxxxxxx...
```
Configure your MCP client:
- **URL** `http://localhost:8000/mcp/sse`
- **Header** `Authorization: Bearer mbr_...`
Then ask the assistant to `save_memory` / `search_memories` — it round-trips through
Postgres. Health check: `curl localhost:8000/health` → `{"status":"ok"}`.
## Configuration
All via environment variables (see [.env.example](.env.example)):
| Var | Purpose |
|---|---|
| `DATABASE_URL` | Postgres 16 + pgvector connection string |
| `OPENAI_API_KEY` | Embeddings (`text-embedding-3-small`, 1536-dim). Optional. |
| `DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL` | Alternative OpenAI-compatible embedding endpoint |
| `PUBLIC_BASE_URL` | Public URL of the MCP server |
| `MEMORY_CAP` / `ARCHIVE_BYTES_CAP` | Optional soft quotas (blank = unlimited) |
## Scope & notes
This is the **engine core**, extracted from the larger [mory](https://usemory.com) product.
A few honest edges:
- **Auth** is MCP bearer tokens (single-user friendly; mint with the dev script above).
For multi-user web deployments, wire your own OIDC/JWT verification in
`backend/auth/dependencies.py` — the seam is already there.
- **`recall_chat`** works out of the box. `search_vault` / `expand_vault` read a summary
DAG that is *populated by a background builder not included in this core* — the
search/drill side and schema ship here; the builder cron does not.
- **Isolation** is enforced at the application layer (`WHERE user_id = %s` on every
query), not via database RLS. See ARCHITECTURE.
## License
[MIT](./LICENSE)
