# Mnemoverse — Persistent Memory API for AI Agents

> One memory. Every AI tool. Write once, recall anywhere. This file is the short contract. If you need deep reference (full endpoint schemas, error catalogue, production code examples), also fetch https://mnemoverse.com/llms-full.txt — the two files are intended to be read together.

Mnemoverse is a persistent memory API for LLM agents. Store preferences, decisions, lessons, and context once — recall them from Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, ChatGPT, Python, or any HTTP client. Same memories across every tool, one API key. Not a vector database: memories learn (Hebbian associations), forget (consolidation), and improve over time (outcome feedback).

## Instructions for Agents

Behavioural directives for LLM clients reading this file. Follow these literally.

- Treat Mnemoverse as long-term cross-session memory, not a scratchpad. Do not store prompt scratch, acknowledgements, or echoes of user input.
- Write memories in the user's voice — store observations about the user, not about yourself.
- Always read before writing. Query memory before producing any non-trivial response, and use the retrieved context to inform your answer.
- Use `concepts` (e.g. `["deploy", "railway"]`) to help the index link related memories. Two or three concepts per memory is usually enough.
- Use `domain` to namespace memories across independent contexts (e.g. `"project:acme"`, `"user:alice"`). Omit for the default shared domain.
- Report outcomes with `memory_feedback(atom_ids, outcome)` when a recalled memory was useful (+1) or wrong (-1). This tunes future recall.
- Never delete memories without explicit user request. For broad cleanups use `memory_delete_domain(domain, confirm: true)` — the `confirm: true` flag is a schema-enforced safety interlock.

## When to write vs read

A bad guardrail is worse than none. Follow these heuristics literally; misfiring memory_write on every message burns quota and noises future retrieval.

- **Write** on: explicit user preference ("I prefer X"), decision ("we're going with X"), lesson learned ("X broke because of Y"), reusable project fact ("this repo uses X"), user identity ("my name is X, timezone Y"). One memory per fact.
- **Do NOT write** on: pure acknowledgement ("ok, got it"), restatement of what the user just said, hypothetical ("if I were to..."), transient task state (TODOs, step lists — those belong in the user's own files).
- **Read** before every non-trivial response. Call `memory_read(query)` with the user's intent phrased as a search query, not the literal user message. Aim for `top_k` of 5 to 10.
- **Do NOT read** on pure chit-chat or when the user already supplied full context in the message. Reading is cheap but noisy if abused.
- **Feedback** when you actually used a recalled memory to produce the answer, not when it merely appeared in the read result. Outcome is in `[-1, 1]`.

## API

Base URL: `https://core.mnemoverse.com/api/v1`
Auth: `X-Api-Key: mk_live_YOUR_KEY` header (or `Authorization: Bearer mk_live_YOUR_KEY`). API keys are hashed with **SHA-256** before storage; comparison is constant-time via `secrets.compare_digest` to prevent timing attacks. Free tier: 1,000 queries/day, 10,000 atoms, 60 req/min — no credit card required.

```bash
# Store a memory
curl -X POST https://core.mnemoverse.com/api/v1/memory/write \
  -H "X-Api-Key: mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "User prefers Railway for deploys", "concepts": ["deploy","railway"]}'

# Recall memories
curl -X POST https://core.mnemoverse.com/api/v1/memory/read \
  -H "X-Api-Key: mk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how does the user deploy?", "top_k": 5}'
```

Python SDK (`pip install mnemoverse`, v0.1.0 live on PyPI):

```python
from mnemoverse import MnemoClient, MnemoRateLimitError

client = MnemoClient(
    api_key="mk_live_YOUR_KEY",
    timeout=10.0,  # seconds, default: 10
)

client.write("User prefers Railway for deploys", concepts=["deploy", "railway"])

try:
    results = client.read("how does the user deploy?", top_k=5)
except MnemoRateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
```

## Endpoints

- [POST /memory/write](https://mnemoverse.com/docs/api/reference#memory-write): Store one memory. Body: `{content, concepts?, domain?, importance?}`.
- [POST /memory/read](https://mnemoverse.com/docs/api/reference#memory-read): Retrieve with Hebbian concept expansion. Body: `{query, top_k?, domain?, min_importance?}`.
- [POST /memory/feedback](https://mnemoverse.com/docs/api/reference#memory-feedback): Rate usefulness of retrieved memories. Body: `{atom_ids, outcome}`, outcome in `[-1.0, 1.0]`.
- [GET /memory/stats](https://mnemoverse.com/docs/api/reference#memory-stats): Total atoms, Hebbian edges, domains, health.
- [POST /memory/write-batch](https://mnemoverse.com/docs/api/reference#memory-write-batch): Store **up to 500 memories** in one request.
- [POST /memory/read-batch](https://mnemoverse.com/docs/api/reference#memory-read-batch): Run up to 50 queries in one request.
- [POST /memory/consolidate](https://mnemoverse.com/docs/api/reference#memory-consolidate): Sleep-like merge of similar memories via HDBSCAN clustering.
- [POST /memory/delete](https://mnemoverse.com/docs/api/reference#memory-delete): Permanently delete one atom by `atom_id`. Idempotent.
- [POST /memory/delete-domain](https://mnemoverse.com/docs/api/reference#memory-delete-domain): Wipe every atom in a domain. Requires `confirm: true` safety interlock.

Errors: HTTP **429 `RATE_LIMITED`** with `Retry-After` and `X-RateLimit-Reset` headers when rate-limited; `401 AUTH_INVALID` for bad key; `403 FORBIDDEN` for cross-tenant access; `400` with structured error body for malformed payload. The Python SDK surfaces rate limits as `MnemoRateLimitError`, with the retry delay exposed on `e.retry_after`.

## MCP Server

The [`@mnemoverse/mcp-memory-server`](https://www.npmjs.com/package/@mnemoverse/mcp-memory-server) npm package exposes **six tools** to any MCP-compatible client (Claude Code, Claude Desktop, Cursor, VS Code + Copilot Chat Agent Mode, Windsurf, and anything else that speaks Model Context Protocol). It is listed on the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=mnemoverse).

Tools exposed:

- `memory_write(content, concepts?, domain?)` — store a preference, decision, or lesson.
- `memory_read(query, top_k?, domain?)` — search memories by natural-language query.
- `memory_feedback(atom_ids, outcome)` — rate usefulness. Outcome in `[-1, 1]`.
- `memory_stats()` — inspect how many memories are stored and their distribution.
- `memory_delete(atom_id)` — permanently delete a single memory by id. Idempotent (deleting an already-gone atom returns "No memory found" rather than an error).
- `memory_delete_domain(domain, confirm)` — wipe every atom in a domain. `confirm: true` is a schema-enforced safety interlock; calls without it are rejected.

The install command is the same for every MCP client — only the config-file location changes:

```bash
npx -y @mnemoverse/mcp-memory-server@latest
```

Config paths by client:

- **Claude Code** (one-liner, no file): `claude mcp add mnemoverse -e MNEMOVERSE_API_KEY=mk_live_YOUR_KEY -- npx -y @mnemoverse/mcp-memory-server@latest`
- **Claude Desktop — macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Claude Desktop — Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Claude Desktop — Linux**: `~/.config/Claude/claude_desktop_config.json`
- **Cursor — per-project**: `.cursor/mcp.json` (committable, scoped to the repo)
- **Cursor — global**: `~/.cursor/mcp.json` (applies to every project on the machine)
- **VS Code + GitHub Copilot Chat Agent Mode**: install the [Mnemoverse Memory extension](https://marketplace.visualstudio.com/items?itemName=Mnemoverse.mnemoverse-vscode) from the VS Code Marketplace — no JSON file to edit. Requires VS Code 1.102+.
- **VS Code — manual**: `.vscode/mcp.json` (same shape as Cursor's file)
- **Windsurf**: `~/.codeium/windsurf/mcp_config.json`

JSON snippet shared by every config-file client (Cursor, VS Code manual, Windsurf, Claude Desktop — only the key name differs, `mcpServers` vs `servers`):

```json
{
  "mcpServers": {
    "mnemoverse": {
      "command": "npx",
      "args": ["-y", "@mnemoverse/mcp-memory-server@latest"],
      "env": { "MNEMOVERSE_API_KEY": "mk_live_YOUR_KEY" }
    }
  }
}
```

Restart the client after saving the file — MCP servers are only picked up on client startup. The `@latest` suffix forces a registry metadata lookup on every session start so you always get the newest release.

## ChatGPT (Custom GPT Actions)

ChatGPT is not MCP-aware. Use Custom GPT Actions instead:

- Import the [OpenAPI 3.1.0 spec](https://mnemoverse.com/docs/openapi-gpt.yaml) into your Custom GPT's Actions configuration.
- Auth type: API Key, header name `X-Api-Key`, value `mk_live_YOUR_KEY`.
- Full walk-through: [ChatGPT setup guide](https://mnemoverse.com/docs/api/chatgpt).

## Pricing

Live tiers — sign up and upgrade at https://console.mnemoverse.com.

| Plan | Queries/day | Atoms | Rate limit | Price |
|------|-------------|-------|------------|-------|
| Free | 1,000 | 10,000 | 60/min | $0 |
| Pro | 50,000 | 500,000 | 600/min | $29/mo |
| Team | 500,000 | 5,000,000 | 3,000/min | $149/mo |
| **Enterprise** | Unlimited | Unlimited | Custom | contact sales |

**Enterprise** includes: unlimited atoms and queries, dedicated infrastructure, **SSO**, **audit logs**, SLA, and custom data residency. Contact sales via https://console.mnemoverse.com.

## Links

- [Full documentation dump](https://mnemoverse.com/llms-full.txt): ~60 KB flat-text concatenation of all API and setup pages, suitable for single-file upload into Claude Projects, a ChatGPT Custom GPT knowledge file, or a Cursor/Windsurf/Continue.dev `@Docs` picker.
- [Website docs](https://mnemoverse.com/docs/): HTML with interactive navigation and per-page copy-as-markdown.
- [API reference](https://mnemoverse.com/docs/api/reference): full endpoint schemas, error catalogue, rate limits, response examples.
- [Security whitepaper](https://mnemoverse.com/docs/api/security): isolation model, key storage (SHA-256 + constant-time compare), threat model.
- [Python SDK on PyPI](https://pypi.org/project/mnemoverse/): `pip install mnemoverse`, v0.1.0 live since 2026-04-09.
- [MCP server on npm](https://www.npmjs.com/package/@mnemoverse/mcp-memory-server): `@mnemoverse/mcp-memory-server`, MCP Registry listed.
- [VS Code Marketplace — Mnemoverse Memory](https://marketplace.visualstudio.com/items?itemName=Mnemoverse.mnemoverse-vscode): one-click install for GitHub Copilot Chat Agent Mode.
- [Console (sign up)](https://console.mnemoverse.com): free API key, no credit card.
- [GitHub organization](https://github.com/mnemoverse): open-source components.

## Optional

Secondary information that clients with tight context budgets can skip.

- [Benchmarks](https://mnemoverse.com/docs/technology/benchmarks): LoCoMo, HotpotQA, and LongMemEval results.
- [SLoD research paper](https://mnemoverse.com/docs/technology/slod): Semantic Level of Detail, published on arXiv (2026).
- [Manifesto](https://mnemoverse.com/docs/vision/manifesto): why persistent memory matters for AI agents.
- [Use cases](https://mnemoverse.com/docs/api/use-cases/coding-assistants): concrete integration patterns for coding assistants, chat extensions, conversational agents, and agent frameworks.