Mnemo

A portable, user-level memory layer for AI agents — shared across agents, exposed over MCP, with no embeddings required by default.

Named after Mnemosyne, the goddess of memory. Mnemo is a single-file, portable memory layer that any MCP-capable host can mount. Migrating it is as simple as copying one database file.

Features

• User-level, cross-agent memory — different agents remember the same you.

• MCP stdio server — mountable by any Model Context Protocol host.

• No embeddings by default — a deterministic, auditable, portable blend of SQLite + FTS5 (BM25 full-text) + a lightweight relations table.

• Optional vectors — sqlite-vec + a local bge-small model available as an opt-in (disabled by default) enhancement.

• Web admin UI — a zero-build local React app to browse, search, edit, delete, inspect audit chains and relation graphs, and run consolidation.

• Chinese full-text search — write-time segmentation via the built-in Intl.Segmenter (zero dependencies) makes even two-character terms recallable.

Related MCP server: memento

Design principles

1. Hybrid architecture (full-text + relations, vectors optional).

2. Facts carry a validity period rather than being destructively overwritten.

3. Agent-generated facts are first-class and stored.

4. Background consolidation (dedup / conflict expiry / aging).

5. Everything is readable, editable, and deletable.

Quick start

npm install
npm run build     # tsc -> dist/
npm test          # node --experimental-strip-types --test

Web admin UI

npm run build
npm run ui        # serves http://127.0.0.1:4173  (alias: mnemo-ui)

From the browser you can browse/filter (by scope / kind / subject / tag), run full-text search (two-character CJK terms are recallable), create / edit / soft-delete / hard-delete facts, inspect audit chains (the superseded_by lineage), view the relation graph (SVG), and run consolidation manually (dry-run preview → commit).

• Backend (src/web.ts): a zero-dependency Node HTTP server (node:http) that reuses store.ts / consolidate.ts to read and write the SQLite database directly, with a REST surface under /api/*. Configurable via MNEMO_UI_PORT (default 4173), MNEMO_UI_HOST (default 127.0.0.1), and MNEMO_DB.

• Frontend (public/): React 18 loaded from a CDN via importmap, with JSX compiled in the browser by Babel-standalone — no npm dependencies and no build step.

• The UI and any mounted stdio MCP server share the same database file safely (SQLite WAL, multiple connections).

MCP tools

Seven MCP tools are exposed:

Tool prefix: mcp__mnemo__*.

Storage & runtime

• Storage: better-sqlite3 (prebuilt binary, no compilation) + FTS5 (unicode61) + a fact_tags table + a relations table; opened with WAL, busy_timeout, and foreign_keys on.

• Chinese retrieval: write-time segmentation with Intl.Segmenter (zero dependencies) so two-character words are recallable.

• The five principles in practice: source ∈ {user, agent}; valid_from / valid_until / superseded_by (old facts are marked invalid, never dropped); soft and hard delete; dedup_key-based conflict expiry; UTC timestamps throughout.

• The runtime database defaults to ~/.dsh/mnemo.db and is independent of the code location; override it with the MNEMO_DB environment variable.

Mounting in an MCP host (stdio)

mnemo:
  command: node
  args: ["<path-to>/Mnemo/dist/index.js"]
  env:
    MNEMO_DB: "~/.dsh/mnemo.db"   # shared database; this is also the default

Build first (npm install && npm run build to produce dist/index.js), then point your host's MCP configuration at it. The stdio transport ships with the MCP SDK, so mounting works out of the box.

Documentation

• docs/design.md — full design document (storage schema, MCP tool interface, consolidation, injection strategy, milestones).

License

MIT