mcp-memory: Instructions file for Codex

mcp-memory — Agent Guide

Bun-only MCP server for persistent memory across OpenCode sessions. Markdown files on disk + SQLite FTS5 search.

Runtime & Build

• Bun only — uses bun:sqlite, runs .ts directly. NOT Node.js-compatible.
• tsconfig.json has noEmit: true; no compile step needed.
• Only dependency: @modelcontextprotocol/sdk.

Key Commands

bun install                          # install
bun run src/index.ts                 # dev / run directly
bunx @mimochamber/memory-server      # run published version

Tests (all are child-process integration tests over JSON-RPC stdio)

bun run test.mjs                # smoke test
bun run test-dedup.mjs          # dedup test
bun run test-compaction.mjs     # compaction append test

• Tests spawn the server as a child process via bun run src/index.ts.
• All set MCP_MEMORY_POLL_INTERVAL=0 to disable compaction polling.
• Use .test-memory/ temp dir (in .gitignore), cleaned up after run.
• No test framework — plain .mjs scripts, JSON-RPC over stdin/stdout.
• There is no CI pipeline (no .github/workflows/).

Publishing

.\scripts\publish.ps1            # dry-run (npm pack --dry-run)
.\scripts\publish.ps1 -Execute   # npm publish --access public

Architecture

Single module, 5 source files:

src/
  index.ts      — MCP server setup, tool handlers, compaction poller
  store.ts      — MemoryStore: SQLite DB + file ops (core logic)
  fts-query.ts  — Builds FTS5 MATCH expression from user query (OR-join tokens)
  paths.ts      — Memory directory layout, path parsing/building, safety checks
  types.ts      — TypeScript types
bin/
  mcp-memory.js — npm binary entry (chdirs to pkg dir, imports src/index.ts)

Entry point

• Dev: src/index.ts — imports directly, Bun runs it.
• Production: bin/mcp-memory.js — changes CWD to package root, then import("../src/index.ts").

MemoryStore (src/store.ts)

• SQLite DB (memory.db) with FTS5 virtual table in external-content mode.
• FTS5 tokenizer: porter unicode61 (does NOT split CJK individually by default).
• CJK preprocessing: addCjkSpacing() inserts spaces after every CJK character before FTS5 indexing, so each CJK character becomes a separate FTS5 token. removeCjkSpacing() reverses this on search results. Both query and content go through this pretreatment.
• Triggers auto-sync memory_fts table ↔ FTS5 index on INSERT/UPDATE/DELETE.
• Fingerprint = ${size}-${mtimeMs} for incremental reconcile.
• Path safety: assertSafeComponent rejects .., null bytes, Windows absolute paths.
• Write safety: per-file writeQueue serializes concurrent compaction appends.