mnemon-memory-mcp: Instructions file for Claude Code

mnemon-mcp

MCP server providing persistent layered memory for AI agents. SQLite + FTS5 backend, zero-cloud, stdio transport.

Part of the Mnemon ecosystem. KB lives in ~/dev/mnemon/mnemon-kb. Task board shared with KB: ~/dev/mnemon/mnemon-kb/tasks/BOARD.md (T-NNN IDs).

Commands

npm run build      # compile TypeScript → dist/
npm run dev        # run via tsx (no build needed)
npm start          # run compiled dist/index.js (blocks on stdio — see Smoke Test)
npm test           # vitest (272 tests: 23 md-parser + 16 kb-import + 28 date-extractor + 48 validation + 133 integration + 8 embedder + 6 MCP dispatch + 5 http + 5 hybrid RRF)
npm run import:kb  # import mnemon-kb markdown → SQLite (skip unchanged)

Full re-import (ignore hashes, rewrite all):

npx tsx src/import/cli.ts --kb-path ~/dev/mnemon/mnemon-kb --force

Smoke test (verify server responds to JSON-RPC):

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js

Tech Stack

Tool	Version	Purpose
TypeScript	5.9	Strict mode, NodeNext modules
better-sqlite3	12.6	Synchronous SQLite (ideal for MCP stdio)
@modelcontextprotocol/sdk	1.27	MCP server framework
zod	4.3	Runtime input validation
snowball-stemmer.jsx	0.2.3	Russian/English stemming
vitest	3.2	Test runner
tsx	4.21	TypeScript execution without build step

Architecture

src/
  index.ts              MCP server entry (stdio transport, tool dispatch)
  index-http.ts         HTTP transport entry (StreamableHTTP, Bearer auth)
  db.ts                 SQLite schema, migrations, indexes, FTS5 triggers
  types.ts              TypeScript types (mirrors SQLite schema)
  tools/
    memory-add.ts       Insert memory, auto-supersede on source_file match
    memory-search.ts    FTS5 search with layer/scope/date filtering, recency boost, query-centered snippets
    memory-update.ts    In-place update or superseding chain
    memory-inspect.ts   Layer stats or single-memory history trace
    memory-export.ts    Export to json/markdown/claude-md with layer/scope/date filters
    memory-health.ts    Diagnostic report + optional expired entry cleanup
    session.ts          Session lifecycle: start, end, list
  import/
    cli.ts              CLI entry for KB import
    kb-config.ts        Import routing rules (which files → which layer)
    kb-import.ts        Bulk import engine (hash-based dedup)
    md-parser.ts        Markdown → memory records splitter
    __tests__/
      md-parser.test.ts 14 unit tests