project-memory-mcp

project-memory-mcp

Persistent AI knowledge base for Claude via Model Context Protocol — fully offline, no cloud API key required.

Stores architectural decisions, technical debt, project progress, and domain knowledge in versioned Markdown files. Claude reads these files automatically via MCP Resources and writes new entries via MCP Tools.

Features

• 4 MCP Resources — Claude reads memory://decisions, memory://tech-debt, memory://progress, memory://context automatically at session start
• 7 MCP Tools — add_decision, log_tech_debt, update_progress, add_context, get_memory, search_memory, reindex_memory
• Semantic Search — Embedding-based search via @huggingface/transformers (all-MiniLM-L6-v2) stored locally in SQLite
• Git Hook — Post-commit hook sends diff + message to Ollama for automatic summarization and auto-commits the updated memory files
• Filesystem Watcher — Changes to CLAUDE.md, docs/adr/, etc. trigger memory updates
• Session Summary — Inactivity timer writes a session summary to progress.md
• Ollama Fallback — Keyword extraction when Ollama is unavailable

Prerequisites

• Node.js >= 20
• Ollama (optional, for automatic summarization)

ollama pull llama3.2

Installation

In a new project (recommended)

npx @pnientiedt/project-memory-mcp init

This sets up everything automatically:

• Creates .project-memory/config.yaml with documented defaults
• Adds project-memory entry to .mcp.json
• Updates .gitignore with database/log exclusions
• Installs the git post-commit hook
• Pulls llama3.2 if Ollama is running

From source

npm install
npm run build

Register the MCP server in Claude Code (.mcp.json already pre-configured):

{
  "mcpServers": {
    "project-memory": {
      "command": "npx",
      "args": ["@pnientiedt/project-memory-mcp"]
    }
  }
}

Usage

After startup Claude reads the memory files automatically. New entries are written via tools:

add_decision    — Save an architectural decision (ADR format); upsert=true to replace existing
log_tech_debt   — Record technical debt; upsert=true to replace existing
update_progress — Update a milestone; upsert=true to replace existing
add_context     — Save domain knowledge / conventions; upsert=true to replace existing
get_memory      — Read a memory file directly
search_memory   — Semantic search across the knowledge base
reindex_memory  — Rebuild the embedding index

Configuration

.project-memory/config.yaml (created with defaults on first run):

ollama:
  base_url: "http://localhost:11434"
  model: "llama3.2"
  timeout_seconds: 60
  fallback_to_keywords: true

embeddings:
  model: "Xenova/all-MiniLM-L6-v2"
  db_path: ".project-memory/embeddings.db"

git:
  hook_enabled: true
  hook_port: 47832
  skip_keyword: "[skip-memory]"

watcher:
  enabled: true
  paths: ["CLAUDE.md", "docs/adr/", "README.md"]
  debounce_ms: 2000

session:
  inactivity_timeout_minutes: 30
  summarize_on_end: true

Environment variables override config:

| Variable | Overrides | |----------|-----------| | PMM_OLLAMA_URL | ollama.base_url | | PMM_OLLAMA_MODEL | ollama.model | | PMM_HOOK_PORT | git.hook_port | | PMM_LOG_LEVEL | logging.level |

Memory Files

Located in .project-memory/ and versioned in git (except embeddings.db and server.log):

| File | Contents | |------|----------| | decisions.md | Architectural decisions (ADRs) | | tech_debt.md | Technical debt | | progress.md | Project progress & session summaries | | context.md | Domain knowledge & conventions |

Development

npm test              # Run tests (101 tests)
npm run test:coverage # Coverage report (83% line coverage)
npm run build         # Compile TypeScript
npm run typecheck     # Type check only
npm run release       # typecheck + test + build + npm publish

Project Structure

src/
  index.ts              # Entry point, stdio transport
  server.ts             # MCP server factory
  config.ts             # Load & validate configuration (zod)
  types.ts              # Shared TypeScript types
  resources/
    memory.ts           # MCP resources (memory://)
  tools/
    write.ts            # add_decision, log_tech_debt, update_progress, add_context
    read.ts             # get_memory, search_memory
    admin.ts            # reindex_memory
  services/
    file.ts             # Atomic read/write of memory files
    embedding.ts        # transformers.js + cosine similarity
    db.ts               # SQLite schema (WAL mode)
    ollama.ts           # Ollama HTTP client + keyword fallback
    summarization.ts    # Prompts per memory category
    git.ts              # simple-git integration
  triggers/
    git-hook.ts         # HTTP server for post-commit hook
    watcher.ts          # Filesystem watcher (chokidar)
    session.ts          # Inactivity timer & session summary
hooks/
  post-commit           # Shell script for git hook