# Memento — full content snapshot > This file is the full README, ARCHITECTURE, and every published > blog post concatenated into a single document for one-shot > ingestion by LLM crawlers (per the llmstxt.org convention). > Generated at build time from the source repository at > https://github.com/veerps57/memento — always in sync. The short, link-rich index lives at https://runmemento.com/llms.txt. The blog index (HTML) lives at https://runmemento.com/blogs/, and an RSS feed at https://runmemento.com/blogs/rss.xml. ---

Memento

CI CodeQL npm MCP Registry License: Apache-2.0 Node.js: 22.11+

A local-first, LLM-agnostic memory layer for AI assistants
runmemento.com

Every AI session starts the same way: re-explaining your preferences, your project's conventions, the decisions you made last week, 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. Memento is one place where that memory lives. It runs an [MCP](https://modelcontextprotocol.io) server over a local SQLite file, so any MCP-capable AI assistant — Claude Desktop, Claude Code, Cursor, GitHub Copilot, Cline, OpenCode, Aider, a research bot, a custom agent — can read and write durable, structured memory about you, your work, and your decisions. Local-first, no outbound network calls by default, no vendor lock-in.

Claude Chat answering 'what did we lock-in for the dashboard revamp last week?' by recalling memories from Memento — the assistant uses the Memento integration, calls search and confirm, and returns a structured answer with no re-explanation from the user

A fresh chat with no prior context — Memento supplies the memory of what was decided last week.

## Quickstart Three steps from zero to a working memory layer: ### 1. Run `init` (interactive on a TTY) ```bash npx @psraghuveer/memento init ``` Creates the database under the XDG default (`$XDG_DATA_HOME/memento/memento.db`, typically `~/.local/share/memento/memento.db` on POSIX), runs migrations, and — on a TTY — walks you through four one-keystroke setup questions: - **Your preferred name.** Stored as the `user.preferredName` config key so memories read "Raghu prefers …" instead of "The user prefers …". - **Install the bundled skill?** One y/N. Copies [`skills/memento/`](skills/memento/SKILL.md) into `~/.claude/skills/` for clients that load Anthropic-format skills. - **Seed with a starter pack?** Pick one of four bundled packs (`engineering-simplicity`, `pragmatic-programmer`, `twelve-factor-app`, `google-sre`) so your store has useful memories on day one. Skip to start empty. - **Auto-install the persona snippet?** Detects AI clients on your machine and writes a marker-wrapped block to each one's user-scope custom-instructions file (`~/.claude/CLAUDE.md` for Claude Code, `~/.config/opencode/AGENTS.md` for OpenCode, `~/Documents/Cline/Rules/memento.md` for Cline). Idempotent and removable. UI-only clients (Cowork, Claude Desktop, Claude Chat, Cursor User Rules) get printed paste instructions instead. Then prints copy-paste MCP snippets for every supported client. Idempotent — re-run any time to reprint the snippets and re-ask anything you skipped. Pass `--no-prompt` to suppress the interactive flow (CI, scripts). ### 2. Connect your AI client `init` prints either a one-line subcommand (where the client ships one) or a JSON snippet to merge into the client's MCP config. Pick the one for your client, paste it, then **restart the client** so it loads the new MCP server. The full per-client walkthrough lives in [docs/guides/mcp-client-setup.md](docs/guides/mcp-client-setup.md). ### 3. Confirm the persona snippet reaches your assistant Memento ships three teaching surfaces — an MCP `instructions` spine on the wire, a bundled skill for skill-capable clients, and the persona snippet. Of the three, **only the persona snippet is guaranteed to reach the assistant's system prompt on every message** — the MCP spec leaves `instructions` optional and client implementations vary in whether they surface it; the skill is intent-triggered so it doesn't fire on neutral first messages. If you said `Y` to the persona auto-install prompt in Step 1, this is already done for every file-based AI client detected on your machine — the snippet was written to `~/.claude/CLAUDE.md`, `~/.config/opencode/AGENTS.md`, and/or `~/Documents/Cline/Rules/memento.md` as applicable. For **UI-only clients** (Cowork, Claude Desktop, Claude Chat at `claude.ai`, Cursor User Rules) and for any client you have where the auto-installer didn't fire, copy the persona snippet from [`docs/guides/teach-your-assistant.md`](docs/guides/teach-your-assistant.md) and paste it into the client's custom-instructions / system-prompt slot (the field's name varies — "Custom Instructions" in the client's settings UI, etc.). That's it. Verify the wire works end-to-end with `npx @psraghuveer/memento verify-setup` — a write/search/cleanup round-trip that proves your assistant can actually call Memento. Then try a fresh session: *"Remember that I prefer pnpm over npm for Node projects."* In the next session, ask *"What's my preferred package manager?"* and the assistant should recall it without you re-explaining. ## 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. ```bash memento pack install engineering-simplicity ``` That command installs one of the bundled packs — eleven memories distilled from John Maeda's *The Laws of Simplicity*. Four bundled packs ship out of the box: `engineering-simplicity`, `pragmatic-programmer` (Hunt & Thomas's tips), `twelve-factor-app` (Wiggins / Heroku), and `google-sre` (Google's SRE books). Preview before installing with `memento pack preview `; list what's installed with `memento pack list`; remove any time with `memento pack uninstall --confirm` (dry-run by default). Packs are also how you share. Author one from your existing memories with `memento pack create`, then distribute it as a file, an HTTPS URL, or a community contribution. The reserved `pack::` tag stamps every pack-installed memory so provenance never drifts. Full guide: [docs/guides/packs.md](docs/guides/packs.md). Design rationale: [ADR-0020](docs/adr/0020-memento-packs.md). ## Getting started **Prerequisites.** Node.js ≥ 22.11, and a C/C++ toolchain so `better-sqlite3` can compile on platforms without a prebuild (Xcode command-line tools on macOS, `build-essential` on Debian/Ubuntu). Run `init` once to set things up: ```bash npx @psraghuveer/memento init ``` `init` defaults the database to the XDG data dir; pass `--db /custom/path/memento.db` (or set `MEMENTO_DB=/custom/path/memento.db`) if you want a non-default location. To run the server directly (e.g. for debugging): ```bash npx @psraghuveer/memento serve ``` The server listens on stdio for [MCP](https://modelcontextprotocol.io) requests. To pass extra flags (e.g. a custom database location): ```bash npx @psraghuveer/memento serve --db ~/.local/share/memento/memento.db ``` You can also point at an existing database with the `MEMENTO_DB` environment variable. **Verify the install** by running `npx @psraghuveer/memento doctor` (add `--quick` to skip the DB and embedder probes; add `--mcp` to also scan known MCP client config files). For a one-screen summary of what's in your store, `npx @psraghuveer/memento status`. To inspect what your install can do — registered commands, current config, database location — without speaking MCP, run `npx @psraghuveer/memento context`. To smoke-test the MCP transport end-to-end, `npx @psraghuveer/memento ping`. **Wiring Memento into an MCP client** (Claude Desktop, Claude Code, Cursor, Cline, OpenCode, VS Code Agent mode, …) is covered step by step in [docs/guides/mcp-client-setup.md](docs/guides/mcp-client-setup.md). The TL;DR is the three-step quickstart above: `init` (which auto-installs the persona snippet into detected file-based clients if you say `Y`), paste the MCP-server snippet into your client, then for UI-only clients paste the persona snippet manually. **Vector retrieval** (paraphrase matching on top of FTS) is on by default. The first search triggers a one-time model download (~110 MB) into `$XDG_CACHE_HOME/memento/models` (or `~/.cache/memento/models` / `%LOCALAPPDATA%\memento\Cache\models`); after that, both FTS and vector arms run automatically. If the model has not yet downloaded, search degrades gracefully to FTS-only. For configuration options and library-wiring details, see [docs/guides/embeddings.md](docs/guides/embeddings.md). **Operating the store** day-to-day — `compact`, `backup`, `status`, scheduling — is covered in [docs/guides/operations.md](docs/guides/operations.md). The conflict workflow is in [docs/guides/conflicts.md](docs/guides/conflicts.md). To prime an AI assistant on how to use Memento well, see [docs/guides/teach-your-assistant.md](docs/guides/teach-your-assistant.md) — and, if your client loads Anthropic-format skills, install the bundled [skill](skills/memento/SKILL.md) as on-intent enrichment over the persona snippet. **See and curate your store in a browser.** `npx @psraghuveer/memento dashboard` launches a local-first web UI that reads against your `MEMENTO_DB`: memory counts by kind and scope, audit trail, conflict triage, config inspection, installed packs. Localhost-only, gated by a per-launch random token in the URL the launcher hands the browser, no telemetry. The dashboard is a sibling package ([`@psraghuveer/memento-dashboard`](packages/dashboard/)) shipped under [ADR-0018](docs/adr/0018-dashboard-package.md); see [docs/guides/dashboard.md](docs/guides/dashboard.md) for the full walkthrough. **Stuck?** Common failure modes (better-sqlite3 build errors, `command not found: memento`, `STORAGE_ERROR`s, missing embedder dependency) are covered in [docs/guides/troubleshooting.md](docs/guides/troubleshooting.md). For the contributor workflow (branching, commit conventions, PR checklist) see [CONTRIBUTING.md](CONTRIBUTING.md). AI agents working on the codebase **must** also read [AGENTS.md](AGENTS.md). ## Guiding principles These are the four principles every design decision is judged against. They are documented at length in [ARCHITECTURE.md](ARCHITECTURE.md). 1. **First principles.** Every construct exists because we proved we need it, not because it's how things are usually done. 2. **Modular.** Any component can be replaced without rewriting the rest. 3. **Extensible.** New variants don't require breaking changes. 4. **Config-driven by the user.** Behavior is shaped by configuration, not by code. ## What Memento is Four pillars. Same four words used everywhere else this is described. - **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 (a decision carries its rationale, a todo its due date, a snippet its language). The assistant can 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 instead of silently coexisting. Memories decay if you don't confirm them. You can answer "why is this here?" and "when did it change?" at any time. - **Yours.** Configurable behavior (every retrieval weight, every decay half-life, every scrubber rule), JSONL export and import, Apache-2.0. Carry your memory between machines, leave any time. No vendor lock-in. Plus: LLM-agnostic (works with whatever model your client talks to), MCP-native (Claude Desktop, Claude Code, Cursor, GitHub Copilot, Cline, OpenCode, Aider, custom agents), privacy-conscious (regex scrubber strips secrets before persistence; patterns are user-configurable). ## What Memento is not - Not a chat history store. It records distilled, structured memory — preferences, facts, episodes, lessons — not raw transcripts. - Not a knowledge graph or semantic database. Use the right tools for that. - Not a cloud service. Memory lives on your machine; cloud embedders, sync across machines, and team-shared memory are not part of the product. - Not a plugin platform. The architecture leaves the door open, but Memento ships with a fixed surface to hold the line on quality. The full list of out-of-scope and current limitations is in [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md). ## How it fits together ```text ┌─────────────────────────────────────────────────────────┐ │ Clients: Claude Desktop, Claude Code, Cursor, Copilot, │ │ OpenCode, custom agents, … │ └──────────────────────┬──────────────────────────────────┘ │ MCP (stdio) ┌──────────────────────▼──────────────────────────────────┐ │ memento-server (MCP adapter) │ └──────────────────────┬──────────────────────────────────┘ │ Command registry ┌──────────────────────▼──────────────────────────────────┐ │ memento-core: services, scope resolver, scrubber, │ │ conflict detector, decay engine │ └──────────────────────┬──────────────────────────────────┘ │ Repository interfaces ┌──────────────────────▼──────────────────────────────────┐ │ SQLite (better-sqlite3) + FTS5 + optional sqlite-vec │ └─────────────────────────────────────────────────────────┘ ``` A full architectural walkthrough lives in [ARCHITECTURE.md](ARCHITECTURE.md). Each significant decision has an [Architecture Decision Record](docs/adr/). ## For contributors (human or AI) Contributions are welcome from both human and AI-assisted authors. We treat them with the same standards. - **Read [AGENTS.md](AGENTS.md)** if you are an AI agent or working with one. It is the canonical instruction set; `CLAUDE.md` and `.github/copilot-instructions.md` are thin pointers to it. - **Read [CONTRIBUTING.md](CONTRIBUTING.md)** for development setup, branching, commit conventions, and the PR lifecycle. - **Open a [design proposal issue](.github/ISSUE_TEMPLATE/design_proposal.yml)** before any non-trivial change. - **Use the [PR template](.github/PULL_REQUEST_TEMPLATE.md).** It asks you to justify, not just describe, the change. We use [GitHub Discussions](https://github.com/veerps57/memento/discussions) for questions and ideas; the [issue tracker](https://github.com/veerps57/memento/issues) is for bugs and accepted work. ## License [Apache-2.0](LICENSE). See [NOTICE](NOTICE) for attribution. ## Packages Memento is a small workspace of focused packages. The architecture is documented in [docs/architecture/](docs/architecture/) and the design decisions in [docs/adr/](docs/adr/); both are the source of truth for what Memento does and why. | Package | Notes | | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`@psraghuveer/memento-schema`](packages/schema) | Memory / event / scope / scrubber / conflict / config / result schemas, plus per-`ConfigKey` value schemas. | | [`@psraghuveer/memento-core`](packages/core) | Storage and migrations, memory + event repositories, scope resolver, scrubber, decay engine with `compact` archival pass, conflict detection + supersession workflow, embedding hook + bulk re-embed driver, `EmbeddingProvider` interface, FTS + brute-force vector retrieval pipeline + ranker, and the command registry with validating execute path (ADR 0003). | | [`@psraghuveer/memento-server`](packages/server) | MCP adapter — `buildMementoServer` projects the `@psraghuveer/memento-core` command registry as MCP tools; `serveStdio` wires it to stdio. Used by `memento serve`. | | [`@psraghuveer/memento-embedder-local`](packages/embedder-local) | Local `EmbeddingProvider` backed by transformers.js + `bge-base-en-v1.5`. Ships as a regular dependency; lazy single-flight init downloads the model on first use. See ADR [0006](docs/adr/0006-local-embeddings-only-in-v1.md). | | [`@psraghuveer/memento`](packages/cli) (CLI) | The published `memento` binary (`npx @psraghuveer/memento` or `npm i -g @psraghuveer/memento`). Lifecycle commands (`init`, `serve`, `dashboard`, `context`, `doctor`, `verify-setup`, `status`, `ping`, `backup`, `export`, `import`, `pack`, `store migrate`, `completions`, `explain`, `skill-path`, `uninstall`) plus a generic projection of the registry surface (`memento `). See [docs/reference/cli.md](docs/reference/cli.md). | | [`@psraghuveer/memento-dashboard`](packages/dashboard) | Local-first web dashboard. Hono server in-process with the engine + Vite-built React SPA. Launched by `memento dashboard`; binds `127.0.0.1` only. See [ADR-0018](docs/adr/0018-dashboard-package.md) and [docs/guides/dashboard.md](docs/guides/dashboard.md). | | [`@psraghuveer/memento-landing`](packages/landing) | Marketing landing page. Static SPA, deployed to GitHub Pages on every push to main that touches `packages/landing/**`. Mirrors the dashboard's design tokens; light/dark toggle. Private (not published to npm). | --- # Architecture This file is the entry point to Memento's architecture. It is intentionally short. The deeper documents live in [`docs/architecture/`](docs/architecture/) and [`docs/adr/`](docs/adr/). ## Reading order 1. **[Overview](docs/architecture/overview.md)** — what Memento is, the runtime topology, and the major modules. 2. **[Data model](docs/architecture/data-model.md)** — `Memory`, `MemoryEvent`, `OwnerRef`, `Scope`, and how they relate. 3. **[Scope semantics](docs/architecture/scope-semantics.md)** — how scopes are resolved, layered, and queried. 4. **[Retrieval](docs/architecture/retrieval.md)** — FTS, optional vector search, ranking, and re-ranking. 5. **[Decay and supersession](docs/architecture/decay-and-supersession.md)** — how memories age and how new memories replace old ones. 6. **[Conflict detection](docs/architecture/conflict-detection.md)** — the post-write hook and conflict surfacing. 7. **[Configuration](docs/architecture/config.md)** — `ConfigKey`, layering, validation, and dynamic update. 8. **[Scrubber](docs/architecture/scrubber.md)** — secret redaction and PII reduction at the boundary. 9. **[ADRs](docs/adr/)** — the why behind every load-bearing decision. ## The shape, in one paragraph A user runs `npx memento serve` and their AI client launches it as an MCP server. The server exposes a small set of typed commands (`memory.write`, `memory.search`, `memory.supersede`, etc.) over stdio. Commands are defined once in a registry and projected to both MCP and the human-facing CLI by adapters; parity is structural. A third surface — a local-first web dashboard — is launched by `npx memento dashboard` (ADR-0018) and reads/writes through the same registry. State lives in a local SQLite database with FTS5 (and an optional brute-force vector backend). Every state-changing operation writes an audit event. Behavior — decay half-lives, retrieval weights, conflict thresholds, scrubber rules — is shaped by configuration, not code. There are no outbound network calls by default; the only optional remote interaction is downloading the local embedding model on first use. ## The four guiding principles These shape every decision below. They are repeated here for emphasis. Long-form discussion is in [`AGENTS.md`](AGENTS.md). 1. First principles. 2. Modular. 3. Extensible. 4. Config-driven by the user. ## Module map ```text packages/ ├── schema/ Shared Zod schemas → TS types via z.infer ├── core/ Domain logic: data model, command registry, │ repositories, decay, retrieval, conflict ├── server/ MCP adapter; thin projection of the registry ├── cli/ CLI adapter; thin projection of the registry, │ plus the npx entry point and lifecycle commands │ (`init`, `serve`, `dashboard`, `context`, `doctor`, │ `status`, `ping`, `backup`, `export`, `import`, │ `pack`, `store migrate`, `completions`, `explain`, │ `skill-path`, `uninstall`) ├── embedder-local/ transformers.js + bge-base-en-v1.5 │ Regular dep; lazy-loaded on first embed() ├── dashboard/ Web dashboard adapter (ADR-0018); Hono server │ in-process with the engine + Vite-built React SPA. │ Lazy-loaded by `memento dashboard`. └── landing/ Marketing landing page. Static SPA (Vite + React), private (not published to npm). Deployed to GitHub Pages on push to main; mirrors the dashboard's design tokens. Has no runtime relationship with the rest of the workspace. ``` The dependency graph is acyclic and one-way: `cli`, `server`, and `dashboard` depend on `core`; `core` depends on `schema`; `embedder-local` and `dashboard` are loaded by `cli` only at runtime through dynamic imports, so non-dashboard / non-vector invocations never pay their startup cost. `landing` is standalone — it imports nothing from the other packages and exists in the workspace only to inherit the lint / typecheck / format gates. ## Status See [`KNOWN_LIMITATIONS.md`](KNOWN_LIMITATIONS.md) for the current list of out-of-scope features and active limitations. --- # Blog ## I tried every AI memory tool. Here's why I built another one. Published: 2026-05-17 URL: https://runmemento.com/blogs/i-tried-every-ai-memory-tool/ import from '../components/CodeBlock'; Memory in every AI tool I've used has the same essential shape: a list of entries, each with a vector. Some tools dress it up — Mem0 tags entries with a `user_id` and a `run_id`, Supermemory adds tags, Cursor's memories carried a project scope. Retrieval is cosine similarity over the vectors, possibly filtered by that light metadata. That's the model. No timestamp weighting on retrieval, so a preference you stated 18 months ago outranks a decision you made yesterday whenever the older entry is lexically closer to your prompt. No notion of *kind* at retrieval time — preferences, one-time facts, project decisions, and todos all retrieve through the same heuristic. Rarely an event log you can interrogate — when the assistant surfaces a memory you don't remember writing, you usually can't trace it back to the conversation that produced it. Rarely a conflict detector that catches contradictions at write time — when you change your mind, both versions usually stay in the index at full strength, and which one wins next is a coin flip on embedding geometry. (Mem0's graph backend is the partial exception on a couple of these. None of them have all four.) For an ordinary database we'd never accept this. We'd demand types, indices, audit logs, constraints. We've somehow accepted vector blobs with the word "memory" on the marketing page. That's what made me build another one. I'm aware of the optics — "another AI memory server" in May 2026 reads like another React state library in 2017. The genre is saturated, the survivors are scrappy, and most new entrants are derivative. So before I tell you what I built, I want to be honest about what already exists — and where each of them keeps treating memory as a flat string with a vector when it should be something more. ## The status quo, tool by tool **ChatGPT Memory.** A vector store of facts ChatGPT extracts from your conversations, retrieved by similarity to whatever you're typing now. Zero-config, baked into the product; Anthropic's "Memory Import" launched in March now lets you carry it across to Claude. The architecture beneath the marketing: a flat list with no `kind` distinction, no per-memory event log, no decay over time. When you correct something, the previous version often stays. The memory lives in OpenAI's account, not on your machine. **Cursor Memory.** When it existed, it was a flat collection of facts surfaced to the model on each turn — scoped to project or global, no decay, no audit trail per entry. Cursor removed Memories in v2.1 (late 2025) and pointed everyone at Rules — static instruction files in a project. The migration threads on the Cursor forum are still open as I write this. Whatever the future of the feature, the lesson is durable: when memory lives inside one tool's product roadmap, you're at that roadmap's mercy. **`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, `copilot-instructions.md`.** These aren't memory. They're config files the AI reads on session start. The 2026 convention is "write `AGENTS.md`, symlink the others to it" — that gives you project-level cross-tool consistency. It also gives you no retrieval, no decay, no conflict detection, no notion of when an entry was last confirmed or last contradicted. It works for *"we use pnpm"* and *"tests live in `__tests__/`"*. It does not work for *"what we decided about the rate-limiter on Tuesday."* **Mem0 (self-hosted), formerly OpenMemory MCP.** The closest competitor on the capability axes that matter, and the most serious local-first cross-tool entry in the space. Same MCP delivery, similar client list (Claude Desktop, Cursor, Windsurf, Cline). The gap is real but narrower than for the others: Mem0 has metadata (user, session, tags), so retrieval can filter — that's a partial type system. It has a per-memory `history` API that records `ADD` / `UPDATE` / `DELETE` events with timestamps — a real audit log. Its graph backend has LLM-based conflict resolution at write time: a resolver model decides whether a new fact obsoletes an existing relationship. What it doesn't have: half-life decay on confidence, a rule-based deterministic conflict detector, or kinds like *decision* / *preference* / *todo* that retrieve with different weights. Architecturally it ships as docker-compose with Qdrant for vectors and Postgres for relational state — a real cloud-style stack running on your machine, which is a different commitment than a single SQLite file in your home directory. (OpenMemory launched as a standalone repo in May 2025 and is now sunset in favor of the unified Mem0 self-hosted server.) **Supermemory.** Cloud-hosted MCP memory with tag-based metadata on top of a vector store. *"One memory. Every AI tool."* Closer in shape to ChatGPT Memory than to a typed, audited system. If the cloud is where you want your memory, it's a clean choice. **Cline's Memory Bank.** A methodology, not a memory system. A set of markdown files (`projectbrief.md`, `activeContext.md`, …) that Cline reads on session start. Influential template — many homegrown "AI memory" approaches in the wild are reskins of it. Beautiful for a project; not the right shape for personal preferences that travel between projects, and not retrievable as structured records. **Anthropic's Managed Agents memory** (April 2026, public beta). Container-scoped vector memory for cloud-hosted agents. Different problem entirely — agent state across runs, not your personal memory across tools. I'm leaving out the dozen smaller MCP memory servers that have shown up since the protocol stabilised. Most are good first attempts; none have the combination of capabilities I wanted. ## What I actually wanted After cycling through the list, the shape of what I actually wanted got concrete. Five capability requirements: 1. **Typed.** Memory should know whether an entry is a *fact*, a *preference*, a *decision*, a *todo*, or a *snippet*. Each has different retrieval semantics. Treating them uniformly is the same mistake as a database that stores every row as `TEXT`. 2. **Audited.** Every write should produce an event in an append-only log. If I disagree with what memory holds, I want to see who wrote it, when, and in response to what — not just delete and hope. 3. **Decay-aware.** A preference I stated 18 months ago shouldn't outrank a decision I made yesterday. Confidence in old memories should fade unless re-confirmed. The decay should be applied at query time — not baked into the store — so I can tune the half-life without rewriting data. 4. **Conflict-aware.** When two memories disagree on the same `topic`, the store should *notice* at write time. Silently coexisting is the worst outcome — both versions retain full retrieval weight, and which one wins next is a coin flip. 5. **Durable.** The store should survive sessions, vendor changes, machine moves, and time. Not pinned to one assistant, not pinned to one project, not at the mercy of someone's next product roadmap. And as the delivery mechanism — not the pitch — I wanted all of that running on my machine, in a file I could `cp` and `grep`, with no Docker stack, no Postgres, no Qdrant, no cloud account. ## What Memento is Memento is what I built from that list. It's a typed memory store with an append-only audit log, configurable per-kind confidence decay, and write-time conflict detection. Every memory has a `kind` — `fact`, `preference`, `decision`, `todo`, or `snippet` — and a scope (global, per-repo, or per-session). Preferences and decisions start with a `topic: value` line so contradictions can be parsed. Every state-changing operation produces a `MemoryEvent` in an append-only log. Effective confidence is computed at query time as `stored × decayFactor(now − lastConfirmedAt, halfLife)`, with the half-life configurable per kind. The conflict detector runs as a post-write hook on every write; it doesn't block, it flags. Then — and this is the delivery mechanism, not the pitch — Memento ships as a single MCP server (`npx @psraghuveer/memento serve`) that any MCP-capable assistant can connect to: Claude Code, Claude Desktop, Cursor, GitHub Copilot, Cline, OpenCode, Aider, custom agents. They all read and write the same store. The store is a single SQLite file under your home directory (`~/.local/share/memento/memento.db` by default); a built-in browser dashboard at `npx @psraghuveer/memento dashboard` lets you inspect, audit, and curate it. Vector retrieval runs against local embeddings (`bge-base-en-v1.5` by default) — no cloud calls for embedding, either. Total install footprint: one `npx` command, ~110 MB on disk for the embedding model on first use, no other dependencies. Apache-2.0. Full architecture walkthrough lives in [ARCHITECTURE.md](https://github.com/veerps57/memento/blob/main/ARCHITECTURE.md); each non-obvious decision is preserved as an [ADR](https://github.com/veerps57/memento/tree/main/docs/adr). ## Honest comparison The lens shifts: what matters is whether memory is treated as infrastructure, not where it ships.
| | Typed kinds | Audited | Decay-aware | Conflict-aware | Local + cross-tool | |---|---|---|---|---|---| | ChatGPT Memory | — | — | — | — | — (OpenAI only) | | `CLAUDE.md` / `AGENTS.md` | — | — | — | — | yes (via symlinks) | | Mem0 (self-hosted) | tags only | history API | — | LLM (graph) | yes (via Docker) | | Supermemory | tags only | — | — | — | cross-tool, cloud | | **Memento** | **5 kinds** | **event log** | **per-kind** | **rule-based** | **yes (SQLite)** |
ChatGPT Memory and Supermemory operate as vector stores with light metadata. Mem0 is the closest, with a real history API and graph-mode LLM-based conflict resolution; what it lacks is structured kinds with different retrieval semantics, half-life decay, and deterministic rule-based conflict detection. Memento is the only entry that's typed *and* audited *and* decay-aware *and* conflict-aware — and the difference compounds as memory grows past a few dozen entries and starts retrieving stale things. A long-form per-axis comparison post is on the way; this table is the thumbnail. ## Memory you can put in a vial ![A hooded figure in a candlelit study draws a silvery glowing thread of memory from their temple with a wand, depositing it into a small glass vial held in their other hand — the metaphor for Memento's pack-installable, transferable typed memory.](/og-images/i-tried-every-ai-memory-tool.jpg) Dumbledore's pensieve. Stone basin in the headmaster's office. He pulls silvery strands of memory out of his head with a wand, drops them into the basin, and either re-enters them later or shares them with Harry. Each memory comes out as a discrete, labeled artifact — you can hand one to someone else and they get the *actual experience*, not a retelling of it. That's what packs are. A pack is a YAML bundle of typed, scoped memories. One command installs it: That writes eleven memories distilled from John Maeda's *Laws of Simplicity* into your local store — typed as `decision` or `preference`, scoped global, each one tagged `pack:engineering-simplicity:0.1.0` so its origin survives every future query. Four bundled packs ship: `engineering-simplicity`, `pragmatic-programmer`, `twelve-factor-app`, `google-sre`. Preview before installing, dry-run uninstalls, idempotent re-installs. You can also author one from your own store with `npx @psraghuveer/memento pack create`. Filter by scope, kind, or tag; Memento bundles the matching memories into a YAML you can email, drop on a Gist, or PR into the community registry. The interesting thing this unlocks isn't the four bundled packs. It's the YAMLs your team is going to write. The stack guides — pnpm + Vitest + Tailwind; Rust + Axum + sqlx; Python + uv + Pydantic. The team conventions — your squad's testing rules, your shop's deployment hygiene, the post-mortems you keep re-citing in chat. Each one is text. Each one is reviewable before it lands. Each one stamps its origin on every memory it installs. **Memory you used to keep re-explaining is memory you can hand to someone else.** ## You might not need this A short list of cases where Memento is the wrong answer: - **You just want a scratchpad.** If you don't care about typing, audit trails, decay, or conflict detection — you just want an assistant to remember anything at all — Mem0 or Supermemory are simpler choices. The whole point of Memento is the structure; if the structure isn't what you want, the install cost isn't justified. - **You live in one AI tool.** If you use Claude Code and only Claude Code, `CLAUDE.md` plus the auto-`MEMORY.md` is genuinely enough. The cost of adding another moving part isn't worth it. - **You want cloud sync across machines.** Memento is local-first. If your memory needs to follow you to a different laptop or a phone, Supermemory or Mem0's cloud variant is the right call. (I have ideas about sync; they are explicitly not v1.) - **You hate SQLite.** I will not litigate this. The case for Memento is narrow on purpose. If you're outside it, please use what already works for you. I am explicitly not in the business of converting anyone who's happy. ## Try it If the case above sounds like yours: That command creates the database, runs migrations, walks you through four one-keystroke setup questions, and prints copy-paste MCP-server snippets for every supported client. Restart your client, paste the snippet, and the next session starts with memory. A reasonable first move once you're set up: install a pack to see typed memory in action immediately. Then ask your assistant, in any tool you wired up, *"What does Maeda's Laws of Simplicity say about hidden complexity?"* — it should answer from the eleven memories the pack just installed, no re-explanation needed. That five-second round-trip is what the whole project is about.