enhx-memory

A persistent, project-scoped memory layer for AI coding agents. Exposes a Model Context Protocol (MCP) server with 45 tools for capturing, searching, deduplicating, relating, and maintaining memory records across long-running coding sessions.

Enterprise-grade by default. The server is 100% automatic —

• 🔁 Auto-session: opens a session against the cwd (or INITIAL_PROJECT_PATH) at boot. You never need to call start_session.

• 👀 Cwd watcher: polls process.cwd() and auto-rebinds to a new project when the agent changes directories (worktree, monorepo, etc).

• 🧹 Auto-curate on session boot: scans the project roots listed in AUTO_CURATE_ROOTS (README, CHANGELOG, plan files, decisions, agents, package.json) and runs the extractors to persist typed memories (command, error, decision, reference). Idempotent; only re-runs when an mtime changes.

• 📥 Auto-ingest: user prompts that flow through the MCP transport are persisted as memories with the auto_ingest tag, debounced per project. Three independent ingest paths (transport frame, per-tool args wrapper, POSIX SIGUSR1 debug signal) share a single debounce map, so a payload that arrives twice lands once.

• 🔎 Auto-recall: every project-scoped tool call returns an auto_recalled array of the most relevant pinned / type-weighted / recency-decayed memories — the agent never has to remember to call recall_memories.

• 🧠 Memory Manager enforces dedup, near-duplicate merging, project conventions, and importance scoring.

This is the TypeScript rewrite of the original Python/FastMCP enhx-memory v0.1.0. The two servers share the same SQLite schema (migrations/0001_initial.sql is byte-identical), so existing databases work without modification.

Install

A. npx (recommended — zero install)

npx enhx-memory

B. Global npm

npm install -g enhx-memory
enhx-memory

C. Single binary

Download a binary for your platform from the GitHub release page. The binary bundles Node + the server + the migrations.

Related MCP server: Archivist MCP

What's new in 1.1.0

Six phases of content-aware work landed between 1.0.0 and 1.1.0. If you already have a 1.0.x database, the schema is unchanged — just upgrade.

• Phase 3 — Content ingest. Four new tools (ingest_file, ingest_files, extract_commands, extract_errors) and a FileIngester that respects FILE_INGEST_MAX_BYTES and a binary sniff gate.

• Phase 4 — Auto-curate on session boot. When a session opens, AutoSessionManager runs curate_session against the configured roots. The synthesized session brief is pinned as a memory, so the next open_session_brief returns it instantly.

• Phase 5 — Robust transport ingest hook. Every server.tool(...) call is wrapped so free-text args are inspected for ingestible content. Also wired a POSIX SIGUSR1 handler that reads stdin and ingests it — a power-user escape hatch for dumping debug payloads into memory without going through the MCP client.

• Phase 6 — Recaller v2. recall_memories now applies type weights (RECALL_TYPE_WEIGHTS) and a per-day recency decay (RECALL_RECENCY_DECAY) on top of the FTS5 score. Pinned memories always come first.

• Phase 7 — open_session_brief + export_project_doc. Two new tools that surface the pinned session brief + top-5 recall, and that compose a single Markdown document summarising the active project (capped to FILE_INGEST_MAX_BYTES).

The full test count went from 208 → 323.

MCP client configuration

Claude Desktop / Cursor / Cline

Common — the three knobs most people tweak: log verbosity, how many memories get auto-attached per tool call (the recall cap), and whether the auto-cleanup scheduler runs. Everything else falls back to its default.

{
  "mcpServers": {
    "enhx-memory": {
      "command": "npx",
      "args": ["-y", "enhx-memory"],
      "env": {
        "DATA_DIR": "/path/to/your/data",
        "LOG_LEVEL": "INFO",
        "AUTO_RECALL_LIMIT": "5",
        "ENABLE_AUTO_CLEANUP": "true"
      }
    }
  }
}

Note: there is no MAX_MEMORY_ITEMS — the closest knob is AUTO_RECALL_LIMIT, which caps how many memories are auto-attached to every tool result. To bound total storage, use ENABLE_AUTO_CLEANUP with CLEANUP_INTERVAL_HOURS and SOFT_DELETE_GRACE_DAYS (below).

Fully-configured — every variable the server reads from env, with defaults inline. Drop or change the ones you want to override; everything else is optional.

{
  "mcpServers": {
    "enhx-memory": {
      "command": "npx",
      "args": ["-y", "enhx-memory"],
      "env": {
        "DATA_DIR": "/path/to/your/data",
        "DB_FILENAME": "enhx_memory.db",
        "LOG_LEVEL": "INFO",
        "DEDUP_POLICY": "reject",
        "DEDUP_THRESHOLD": "0.8",
        "ENABLE_AUTO_CLEANUP": "true",
        "CLEANUP_INTERVAL_HOURS": "24",
        "SOFT_DELETE_GRACE_DAYS": "7",
        "ENABLE_AUTO_SESSION": "true",
        "INITIAL_PROJECT_NAME": "",
        "INITIAL_PROJECT_PATH": "",
        "INITIAL_CLIENT": "auto",
        "ENABLE_AUTO_INGEST": "true",
        "AUTO_INGEST_DEBOUNCE_SECONDS": "30",
        "AUTO_INGEST_MIN_LENGTH": "20",
        "ENABLE_AUTO_RECALL": "true",
        "AUTO_RECALL_LIMIT": "5",
        "AUTO_RECALL_MIN_SCORE": "0",
                "AUTO_DETECT_CONVENTIONS": "true",
                "ENABLE_CWD_WATCHER": "true",
                "CWD_CHECK_INTERVAL_SECONDS": "5",
                "ENABLE_FILE_INGEST": "true",
                "FILE_INGEST_MAX_BYTES": "262144",
                "FILE_INGEST_BINARY_SNIFF": "true",
                "AUTO_CURATE_SESSION": "true",
                "AUTO_CURATE_ROOTS": "README.md,CHANGELOG.md,plan*.md,plan/*.md,decisions.md,agents.md,package.json,.github/agents.md",
                "CURATE_PIN_BRIEF": "true",
                "RECALL_TYPE_WEIGHTS": "error:.5,decision:.3,pattern:.25,code:.1,reference:.05,note:0,conversation:0",
                "RECALL_RECENCY_DECAY": "0.95"
              }
    }
  }
}

Globally-installed npm (the env block is optional — only override what you need):

{
  "mcpServers": {
    "enhx-memory": {
      "command": "enhx-memory",
      "env": {
        "LOG_LEVEL": "INFO",
        "AUTO_RECALL_LIMIT": "5",
        "ENABLE_AUTO_CLEANUP": "true"
      }
    }
  }
}

Single binary (same — env block optional):

{
  "mcpServers": {
    "enhx-memory": {
      "command": "/usr/local/bin/enhx-memory",
      "env": {
        "LOG_LEVEL": "INFO",
        "AUTO_RECALL_LIMIT": "5",
        "ENABLE_AUTO_CLEANUP": "true"
      }
    }
  }
}

CLI flags

Without flags, the server starts on stdio.

Environment variables

Note: ENABLE_AUTO_INGEST, ENABLE_AUTO_RECALL, and ENABLE_AUTO_SESSION all default to true so the server runs as a fully automatic memory layer out of the box. Set any of them to false to opt out of that specific behavior.

The 45 tools

Lifecycle (5)

• start_session — open a session against a project (auto-creates if needed). When called with no arguments, delegates to AutoSessionManager and returns an auto_recalled array of relevant memories. Sessions opened via the auto-curate hook also attach a freshly-pinned session brief (see open_session_brief).

• get_project_summary — counts + recent memories for the active project, plus auto_recalled.

• list_projects — all known projects.

• notify_project_change — explicit signal that the agent has switched projects (e.g. into a git worktree, multi-repo monorepo, or any case the cwd watcher can't see). Takes {cwd?, project_name?, root_path?, reason?}; rebinds the active project, opens a fresh session, and returns the new active project + an auto_recalled array.

• get_active_project — return the currently active project and session (auto-recovers a session if none is active).

Conventions (4)

• detect_project_type — sniff files at a root path

• detect_and_save_project_conventions — persist conventions on the project row

• remember_project_pattern — save a project-specific pattern as a memory

• get_project_conventions — return saved conventions

Auto-ingest (2)

• set_auto_ingest — toggle + configure the auto-ingest middleware

• get_auto_ingest_status — current config + counters

Recall & ingest (2)

• recall_memories — free-text recall. Type-weighted + recency-decayed (Recall v2): pinned memories always come first, then FTS hits scored by RECALL_TYPE_WEIGHTS and RECALL_RECENCY_DECAY. Returns RecalledMemory[] with score and reason.

• add_user_message — convenience tool for the agent to persist every user prompt as a conversation-type memory tagged user_prompt. Auto-recall is also attached.

Memories (8)

Every project-scoped tool here returns an auto_recalled array of relevant memories, so the agent never needs to issue a separate recall_memories call.

• add_memory — insert with optional type/tags/importance/file paths

• get_memory — fetch a single row (bumps access count)

• list_memories — paginated list with filters

• search_memories — FTS5 + LIKE search

• update_memory — patch fields on an existing memory

• delete_memory — soft-delete (preserved until cleanup)

• count_memories — fast count with filters

• bulk_add_memories — insert many in one call

Dedup (3)

• find_duplicates — scan project for near-duplicates

• merge_memories — combine two memories (rewires relations, hard-deletes source)

• set_dedup_policy — reject / merge / warn / off + threshold

Relations (5)

• add_relation — directed edge between two memories

• remove_relation — drop edges (optionally filtered by type)

• get_relations — incoming + outgoing edges for a memory

• get_related_memories — BFS up to N hops

• list_relation_types — distinct types currently used

Tasks (4)

• create_task — new task in the active project

• list_tasks — paginated with status/priority filters

• update_task_status — pending / in_progress / done / cancelled

• delete_task — remove by id

Cleanup (3)

• cleanup_old_data — purge soft-deleted rows + VACUUM/ANALYZE

• optimize_memories — drop orphans + canonicalize JSON

• set_cleanup_policy — adjust interval / grace / enable

System (3)

• health_check — DB, FTS, active project, scheduler, auto-ingest status

• get_database_stats — table row counts + size

• get_performance_stats — per-tool call counts, latencies, error rates

Content ingest (4)

Tools for slurping project files into typed memories. Designed to be called by an agent that wants to "remember" what a plan, an error log, or a decisions file says without re-reading it on every turn.

• ingest_file — read a single file (binary sniff + size cap), run the extractors, persist typed memories. Idempotent via content-hash.

• ingest_files — batch over a list of paths in one call.

• extract_commands — pull shell-command lines out of free text and return them as typed command memories (no DB write).

• extract_errors — pull error / stack-trace blocks out of free text and return them as typed error memories (no DB write).

Session & export (2)

• open_session_brief — return the pinned session brief for the active project plus recent memory sections and the top 5 v2-recall hits. Cheap to call; meant to be the first thing the agent reads when it wakes up in a new session.

• export_project_doc — compose a single Markdown document summarising the active project (header, brief, conventions, recent memories, pending tasks, recent errors, frequent commands, recent decisions). Capped to FILE_INGEST_MAX_BYTES. Useful as an AGENTS.md source.

Development

git clone https://github.com/enhx/enhx-memory.git
cd enhx-memory
npm install
npm run typecheck   # tsc --noEmit
npm run lint        # eslint
npm test            # vitest run (323 tests)
npm run build       # tsc → dist/
npm start           # node bin/enhx-memory.mjs (uses dist/)
npm run dev         # tsx src/index.ts (no build needed)

Test coverage is configured to fail under 80 % line coverage (vitest --coverage).

Architecture

src/
  index.ts              # entry — boots DB, AppContext, McpServer, transport
  config.ts             # ServerConfig (zod-validated, env-driven)
  logging.ts            # pino + rotating file
  context.ts            # AppContext (DI bag)
  perf/tracker.ts       # per-tool latency tracking
  errors.ts             # ToolError / DatabaseError / ValidationError
  version.ts            # reads version from package.json at runtime
  util/                 # csv, json, signals, time
  db/                   # DatabaseManager + per-table CRUD (better-sqlite3)
  dedup/                # normalize + MinHash + Jaccard
  domain/               # MemoryManager, RelationsManager, TasksManager,
                        # ProjectConventionLearner, AutoSessionManager,
                        # AutoIngestMiddleware, CleanupScheduler,
                        # FileIngester, MemoryCurator, Recall v2,
                        # extractors (commands/errors/decisions/refs)
  tools/                # 45 MCP tools across 13 register files
                        # (lifecycle, conventions, auto-ingest, recall,
                        #  memories, dedup, relations, tasks, cleanup,
                        #  system, ingest, session-brief, export-project)
                        # + transport wrapper + helpers
migrations/             # 0001_initial.sql (verbatim from Python v0.1.0)
bin/enhx-memory.mjs     # CLI launcher
tests/                  # vitest suite (323 tests across helpers, db,
                        # domain, dedup, unit, integration, tools)

The full rewrite plan is in TS_REWRITE_PLAN.md.

License

MIT