# 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.

## 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

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

### Web admin UI

```bash
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 | Purpose |
|------|---------|
| `save_memory`   | Store a fact (with scope / kind / source / validity). |
| `search_memory` | BM25 full-text search (CJK-aware). |
| `list_memories` | List / filter facts. |
| `update_memory` | Edit a fact (keeps the old version as superseded). |
| `forget_memory` | Soft or hard delete. |
| `link_memories` | Create a typed relation between two facts. |
| `consolidate`   | Deterministic housekeeping (dedup, conflict expiry, aging). |

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)

```yaml
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