~/memento
One memory layer for every AI assistant you use.
Memento is a local-first, LLM-agnostic memory layer. It runs an MCP server over a single SQLite file on your machine, so any MCP-capable AI assistant — Claude Desktop, Claude Code, Cursor, GitHub Copilot, Cline, OpenCode, Aider, a custom agent — can read and write durable, structured memory about you, your work, and your decisions.
Local. Typed. Audited. Yours.
creates the database, runs migrations, prints copy-paste MCP snippets for your client
~/the_pain
Every AI session starts the same way.
Re-explaining your preferences. Re-stating your project's conventions. Re-listing the decisions you made last week and the dead-ends to avoid. Each tool solves this in its own siloed way — CLAUDE.md, .cursorrules, copilot-instructions.md, ChatGPT Memory — but you, the human, are the one constant.
Your memory shouldn't fragment across vendors.
~/recall
Recall, not re-explain.
Open a fresh chat. Ask what you decided last week. The assistant just knows — because Memento is the layer underneath, supplying durable, structured memory the chat itself never had.
~/how_it_works
One place where memory lives.
Memento sits between your AI clients and a SQLite file on your machine. Clients talk to it over MCP; you read and curate via the dashboard or the CLI. The memory model is structured (typed kinds, scopes, audit log, decay), so the assistant can reason about what's still true — not just retrieve text blobs.
AI clients
Claude Desktop · Claude Code · Cursor · GitHub Copilot · Cline · OpenCode · Aider · custom agents
memento serve
Typed command registry · scope resolver · scrubber · decay engine · conflict detector
One SQLite file
Under your home directory · FTS5 + optional vector retrieval · append-only audit log
~/quickstart
Three steps, then you're done.
- 1step
Run init (interactive)
Creates the SQLite database, runs migrations, then walks you through four one-keystroke questions on a TTY — your preferred name, install the bundled skill, seed a starter pack, and auto-install the persona snippet into every file-based AI client detected on your machine (Claude Code, OpenCode, Cline). Then prints copy-paste MCP snippets for every supported client. Pass --no-prompt for CI.
- 2step
Connect your AI client
Paste the JSON snippet into your client's MCP config (file location varies by client), or run the one-line subcommand init prints where the client ships one. Restart the client so it loads the new MCP server. Then verify the wire with `memento verify-setup` — spawns the server as a subprocess and round-trips a write/search/cleanup.
{ "mcpServers": { "memento": { "command": "npx", "args": ["-y", "@psraghuveer/memento", "serve"], "env": { "MEMENTO_DB": "~/.local/share/memento/memento.db" } } } } - 3step
Confirm the persona reaches your assistant
The persona snippet below is the one teaching surface guaranteed to reach the assistant's system prompt on every message — the MCP `instructions` spine (ADR-0026) is optional on the client side and current implementations vary in whether they surface it; the bundled skill is intent-triggered so it doesn't fire on neutral first messages. If init's auto-install prompt fired in step 1, file-based clients are already done. For UI-only clients (Cowork, Claude Desktop, Claude Chat, Cursor User Rules) paste the snippet below into the client's custom-instructions slot.
Persona snippet — the universal always-on teaching surface
Full guide →The MCP spec defines an optional instructions field that servers can use to inject session-start guidance, but client implementations of that field vary considerably. The bundled skill is intent-triggered and doesn't fire on neutral first messages. The persona snippet is the only teaching surface guaranteed to land in your assistant's system prompt on every message — paste it into wherever your client stores user-defined system prompt content (the field name varies — CLAUDE.md, .cursorrules, a "Custom Instructions" textarea in the client's settings UI, etc.) so the teaching contract reaches the assistant regardless of which optional surfaces your client implements.
## Memory (Memento)
You have a local memory store via MCP. Use it as your durable
memory; treat chat as ephemeral.
- Memory ops are silent background plumbing. Don't preface them
("let me check memory") and don't report results ("saved",
"memory was empty"). The UI shows the tool call; layering prose
on top pollutes the conversation. Speak only when the user
asked a question whose answer is in memory, a write surfaced a
conflict, or the user explicitly said "remember this" — and
then one word ("noted") is enough.
- At the start of a task, call `get_memory_context` to load relevant
memories for this session. If context looks thin, call
`search_memory` with specific terms.
- When you actually use a memory, call `confirm_memory` with its id.
- Write durable user statements (preferences, decisions, facts,
todos, snippets) via `write_memory` with an explicit `kind`.
- Before ending a session, call `extract_memory` with a batch of
candidates for anything worth remembering that wasn't written
explicitly during the conversation. The server deduplicates
automatically — when in doubt, include it. The default mode
(`extraction.processing: 'auto'`) runs sync for batches ≤10 and
async above; the `mode` field on the response discriminates.
Don't retry on an async receipt — it lands as memories within
~1–5 seconds.
- `write_memory` and `extract_memory` share one candidate shape
(ADR-0027): `kind` is a discriminated-union object with per-kind
fields nested inside. Use `{"type":"fact"}`,
`{"type":"preference"}`, `{"type":"decision","rationale":"..."}`,
`{"type":"todo","due":null}`, `{"type":"snippet","language":"shell"}`.
- For preferences and decisions, start `content` with a single
`topic: value` line followed by prose. Conflict detection
parses that line; the server rejects offending writes with
`INVALID_INPUT` (governed by `safety.requireTopicLine`,
default true).
- Distillation is **retrieval indexing**, not summarisation. The
future question may ask about any specific date, named entity,
proper noun, action, or object that came up — index every
concrete reference, don't capture the gist.
- Preserve specific terms when distilling. Use the speakers' exact
words for proper nouns, identity qualifiers, places, dates, and
the object of any action. "Raghu researched adoption agencies",
not "researched career options". "Transgender woman", not
"woman". Don't squash enumerations; emit each item or list them
explicitly. When in doubt, include — the server dedups.
- Capture facts about every named participant, not only the user.
If the user mentions someone ("my friend Alex is moving to
Berlin for a SAP job"), emit memories attributed to that named
person (Alex is moving to Berlin; Alex has a new job at SAP),
not collapsed onto the user. The future question may ask about
anyone named in the conversation.
- Emit a candidate for every dated event. If the user mentions an
event with an absolute date ("May 7") or a relative one
("yesterday", "last Tuesday"), resolve to an absolute date and
emit it in the content. Don't fold dated events into untimed
habits — the future "when did X happen?" query can only be
answered by a memory that names the date.
- Capture precursor actions alongside outcomes. When the user
describes a sequence ("researched X then chose Y", "tried A and
settled on B"), emit both — a candidate for the precursor and a
candidate for the outcome. Future questions can target either
step; the outcome never erases the precursor.
- Use the user's preferred name from `info_system.user.preferredName`
when authoring memory content; fall back to "The user" when
that field is null.
- For changes of mind, use `supersede_memory`, not `update_memory`.
- Never write secrets, tokens, or credentials.Then start a fresh session and tell your assistant something durable — "Remember that I prefer pnpm over npm for Node projects." In the next session, ask "What's my preferred package manager?" and watch the assistant recall it without you re-explaining.
~/packs
Seed your store with a pack.
A fresh Memento install is empty. Packs are curated YAML bundles of memories you can install in one step — a stack guide (Rust + Axum, TypeScript + pnpm, Python + uv…), a team's conventions, or a personal set you authored on another machine.
installs eleven memories distilled from John Maeda's The Laws of Simplicity
install
Don't start from empty.
One command installs a curated bundle. Bundled ids, local files, or HTTPS URLs all route through the same install path. `pack preview` rehearses without writing.
author
Bundle what you already have.
`memento pack create` builds a YAML from memories already in your store. Filter by scope, kind, or tag — or pick interactively. The output is human-readable and `git diff`-friendly.
share
Distribute a stack guide in one file.
Email a YAML, drop a GitHub raw URL, or contribute to the community registry. Recipients install with one command. Reserved `pack:<id>:<version>` tags keep provenance honest.
audit
It's still your store.
Pack-installed memories are normal memories — they decay, conflict-detect, and supersede like any other. Uninstall is dry-run by default. Re-install is idempotent.
~/your_store
See what your assistants remember. Curate it in a browser.
Run npx @psraghuveer/memento dashboard for a local-first web UI against your store: search, audit, conflict triage, config inspection. Localhost-only. No auth. No telemetry. Same trust model as the CLI.
~/overview
See your store at a glance
- Active / archived / forgotten / superseded counts
- Distribution by kind (fact, preference, decision, todo, snippet) and by scope
- Last write across all scopes
- Vector retrieval status + open-conflict count
~/memory/$id
Drill into any memory
- Full content, tags, supersession chain
- Provenance: stored confidence, decay-adjusted effective confidence
- Append-only audit timeline — every event since creation
- One-click confirm / unpin / forget — destructive actions gated
⌘K command palette
Search and navigate from anywhere
- Live full-text + paraphrase search as you type
- Type `>` for ranked route navigation
- Type `:` plus a ULID to open a memory by id
- Read-only by design — write verbs stay on detail pages
~/principles
What Memento is.
Local. Typed. Audited. Yours.
Local
One SQLite file under your home directory. No cloud, no telemetry, no outbound network calls by default. Fully offline.
Typed
Five memory kinds — fact, preference, decision, todo, snippet — with kind-specific fields. Reason about what's still true, not just retrieve text blobs.
Audited
Every write produces an event in an append-only log. Conflicts surface for triage. Memories decay if you don't confirm them.
Yours
Configurable behavior, JSONL export, Apache-2.0. Carry your memory between machines, leave any time. No vendor lock-in.
Packs
Curated YAML bundles of memories. Install with one command; share by file, URL, or community registry. Provenance tagged automatically.
Universal
MCP-native and LLM-agnostic. Plugs into Claude Desktop, Claude Code, Cursor, Copilot, Cline, OpenCode, Aider, custom agents — works with whatever model your client talks to.
~/compared_to
Memento vs the alternatives.
The closest comparable tools are vendor-specific: ChatGPT Memory (OpenAI), Claude Projects (Anthropic), and the per-client config files most coding assistants ship with (CLAUDE.md, .cursorrules, copilot-instructions.md). They each solve one slice of the problem; Memento is the only one that's local-first and works across every AI tool you use.
Memento
- Storage location
- Local SQLite file
- Works across AI tools
- Yes (any MCP client)
- Vendor lock-in
- None
- Typed memory model
- Yes (fact, preference, decision, todo, snippet)
- Append-only audit log
- Yes
- Conflict detection
- Built in
- Confidence decay
- Yes (configurable half-life)
- Data portability
- JSONL export / import
- Curated memory bundles
- Yes (packs)
- Offline use
- Fully offline
- Cost
- Free, Apache-2.0
ChatGPT Memory
- Storage location
- OpenAI cloud
- Works across AI tools
- OpenAI only
- Vendor lock-in
- OpenAI
- Typed memory model
- No (free-form text)
- Append-only audit log
- No
- Conflict detection
- No
- Confidence decay
- No
- Data portability
- No (cloud-locked)
- Curated memory bundles
- No
- Offline use
- Online only
- Cost
- Bundled with subscription
Claude Projects
- Storage location
- Anthropic cloud
- Works across AI tools
- Anthropic only
- Vendor lock-in
- Anthropic
- Typed memory model
- No (free-form text)
- Append-only audit log
- No
- Conflict detection
- No
- Confidence decay
- No
- Data portability
- No (cloud-locked)
- Curated memory bundles
- No
- Offline use
- Online only
- Cost
- Bundled with subscription
Per-client config files
- Storage location
- Local repo files
- Works across AI tools
- Per-tool only
- Vendor lock-in
- Per-vendor format
- Typed memory model
- No (free-form text)
- Append-only audit log
- Git (manual)
- Conflict detection
- No
- Confidence decay
- No
- Data portability
- Copy files
- Curated memory bundles
- Manual copy
- Offline use
- Offline (read-only)
- Cost
- Free
~/faq
Frequently asked.
- What is Memento?
- Memento is a local-first, LLM-agnostic memory layer for AI assistants. It runs as an MCP server over a single SQLite file on your machine, so any MCP-capable AI assistant — Claude Code, Claude Desktop, Cursor, GitHub Copilot, Cline, OpenCode, Aider, custom agents — can read and write durable, structured memory about you, your work, and your decisions.
- How is Memento different from ChatGPT Memory or Claude Projects?
- ChatGPT Memory and Claude Projects are vendor-specific — your memory is locked to one model and one company. Memento is local-first and tool-agnostic: the same memory store backs every AI assistant you use, you own the SQLite file, and there's no vendor lock-in. Four pillars summarise the difference. Local: one SQLite file under your home directory, no cloud, no telemetry. Typed: five memory kinds with kind-specific fields, not free-form text. Audited: every write is an event, conflicts surface for triage, memories decay if you don't confirm them. Yours: configurable behaviour, JSONL portable, Apache-2.0.
- What's a Memento pack?
- A pack is a curated YAML bundle of memories you can install in one step. Install the bundled engineering-simplicity pack with `memento pack install engineering-simplicity` and you get eleven memories distilled from John Maeda's The Laws of Simplicity. Author your own from memories already in your store with `memento pack create`, then share by file, HTTPS URL, or community contribution. Packs are how you go from a fresh install to a useful memory layer without re-typing the same preferences and conventions every time. Re-install is idempotent, uninstall is dry-run by default, and every pack-installed memory carries a reserved `pack:<id>:<version>` tag so provenance never drifts. Full guide: https://github.com/veerps57/memento/blob/main/docs/guides/packs.md
- Where is my data stored?
- In a single SQLite file under your home directory. By default, that is the XDG data directory ($XDG_DATA_HOME/memento/memento.db, typically ~/.local/share/memento/memento.db on POSIX systems). No cloud, no telemetry, no outbound network calls by default. Override the path with --db or the MEMENTO_DB environment variable.
- Does Memento work offline?
- Yes. The MCP server runs entirely on your machine. LLM calls happen between your AI client and your model provider; Memento itself never reaches the internet. Optional vector retrieval uses a model that runs locally too.
- Does it cost anything?
- No. Memento is Apache-2.0 licensed and free to use. Install with npx @psraghuveer/memento init.
- Which AI assistants does Memento support?
- Any MCP-capable client. Tested with Claude Desktop, Claude Code, Cursor, GitHub Copilot, Cline, OpenCode, Aider, and the Anthropic Agent SDK. New MCP-capable clients work without code changes — Memento exposes standard MCP tools and the client decides when to call them.
- Does Memento send my data anywhere?
- No. Memento makes no outbound network calls by default. The MCP server runs entirely on your machine, the SQLite file lives in your home directory, and the embeddings model used for vector retrieval is downloaded once on first use and runs locally. Your AI client talks to its model provider as it always does — Memento sits between the client and your local memory store, never between you and your model provider.
- Can I use the same Memento store across multiple machines?
- Memento doesn't sync. The store is a single SQLite file under your home directory; you can copy or symlink it across machines through whatever sync layer you already use (iCloud, Dropbox, Syncthing, rsync, a shared NFS mount). Two machines writing at the same time can corrupt the SQLite WAL — most users keep one primary machine and treat sync as an explicit copy step. For multi-machine workflows, the JSONL export/import is safer than file-level sync.
- What happens to my memory if I switch AI tools?
- Nothing — the memory stays in your SQLite file. Memento exposes the same MCP server to every client, so switching from Claude Code to Cursor to OpenCode is just pointing the new client at the existing Memento server. Memories are never moved or transformed; the new client reads the same store.
- How do I back up or migrate my memory?
- Two options. (1) Copy the SQLite file directly: cp ~/.local/share/memento/memento.db backup.db — the file is fully self-contained. (2) Use the portable JSONL export: npx @psraghuveer/memento export > memories.jsonl, then npx @psraghuveer/memento import < memories.jsonl on the target machine. The JSONL is human-readable and version-controllable; the format is documented in ADR-0013 and stable across versions.
- Does Memento work with custom or self-built MCP clients?
- Yes. Memento exposes the standard MCP protocol over stdio — any client that speaks MCP can talk to it. Build a custom agent with the Anthropic Agent SDK, the OpenAI Agents SDK, a LangChain wrapper, a Python script using mcp-python, or any other MCP-compatible runtime, and point it at npx @psraghuveer/memento serve. No code changes on Memento's side are needed for new client types.