project-memory MCP — Use Cases, Install & Live Demo

Why use it

Key features

Four-file canon: bugs.md, decisions.md, key_facts.md, issues.md
Claude reads them before proposing architectural changes
Three install scopes: global (~/.claude/skills), project (.claude/skills), workspace
Installable via skilz (pip) or plain copy
No database — just Markdown you can diff and review

Live Demo

What it looks like in practice

project-memory-skill.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "project-memory-skill": {
      "command": "pip",
      "args": [
        "install",
        "skilz",
        "&&",
        "skilz",
        "install",
        "SpillwaveSolutions_project-memory/project-memory"
      ],
      "_inferred": false
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "project-memory-skill": {
      "command": "pip",
      "args": [
        "install",
        "skilz",
        "&&",
        "skilz",
        "install",
        "SpillwaveSolutions_project-memory/project-memory"
      ],
      "_inferred": false
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "project-memory-skill": {
      "command": "pip",
      "args": [
        "install",
        "skilz",
        "&&",
        "skilz",
        "install",
        "SpillwaveSolutions_project-memory/project-memory"
      ],
      "_inferred": false
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "project-memory-skill": {
      "command": "pip",
      "args": [
        "install",
        "skilz",
        "&&",
        "skilz",
        "install",
        "SpillwaveSolutions_project-memory/project-memory"
      ],
      "_inferred": false
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "project-memory-skill",
      "command": "pip",
      "args": [
        "install",
        "skilz",
        "&&",
        "skilz",
        "install",
        "SpillwaveSolutions_project-memory/project-memory"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "project-memory-skill": {
      "command": {
        "path": "pip",
        "args": [
          "install",
          "skilz",
          "&&",
          "skilz",
          "install",
          "SpillwaveSolutions_project-memory/project-memory"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add project-memory-skill -- pip install skilz && skilz install SpillwaveSolutions_project-memory/project-memory

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use project-memory

Bootstrap project-memory on an existing codebase

👤 Teams tired of re-explaining the same context to their agent ⏱ ~15 min beginner

When to use: You've been using Claude Code on this repo but context resets every session.

Prerequisites

Python 3.10+ for skilz installer — pyenv or system Python

Flow

Install at project scope

pip install skilz && skilz install SpillwaveSolutions_project-memory/project-memory --scope project✓ Copied

→ .claude/skills/project-memory/SKILL.md appears
Run the bootstrap command

/project-memory — initialize the four files for this repo.✓ Copied

→ docs/project_notes/ created with the four canonical files
Seed decisions.md with 2–3 known choices

Add ADRs for our ORM choice, our error-handling convention, and our CI runner.✓ Copied

→ Three tidy ADR entries

Outcome: Claude now has a persistent, reviewable brain for this repo.

Pitfalls

Committing key_facts.md with secrets — The skill explicitly flags key_facts.md as 'non-sensitive' — never put credentials there

Combine with: memory-bank-mcp

Capture the root cause of a bug so it never comes back

👤 On-call engineers closing out a fire ⏱ ~5 min beginner

When to use: You just fixed something tricky and want the lesson durable.

Flow

Ask Claude to record it

Add this to bugs.md — error was NoneType in billing.retry; root cause: stale idempotency key cache; prevention: TTL on the cache.✓ Copied

→ New bugs.md entry with root cause + prevention

Outcome: A bug catalog that pays dividends next time a similar symptom appears.

Pitfalls

Writing the symptom instead of the cause — Force the entry to have a 'Root Cause' and 'Prevention' section — not just 'what I fixed'

Combine with: github

Let Claude consult decisions.md before suggesting a refactor

👤 Teams who hate re-litigating settled choices with their agent ⏱ ~10 min beginner

When to use: Your agent keeps proposing frameworks/patterns the team already said no to.

Flow

Make sure the decision is in decisions.md

Record: 'We use Repository pattern, not Active Record. Rationale: <x>.'✓ Copied

→ Clear ADR in decisions.md
Ask for the refactor

Propose a refactor of src/billing/ — respect our decisions.md.✓ Copied

→ Proposal references the Repository decision and doesn't suggest Active Record

Outcome: Fewer dead-end proposals that get rejected in review.

Combine with: git

Combinations

Pair with other MCPs for X10 leverage

project-memory-skill + memory-bank-mcp

Use project-memory for the curated canonical four files, memory-bank-mcp for free-form working memory across projects

Write structured ADRs to decisions.md; dump raw session notes into the memory bank.✓ Copied

project-memory-skill + github

After merging a PR, update decisions.md and issues.md as part of the PR description

Open the PR and include the decisions.md diff in the description.✓ Copied

project-memory-skill + git

Review memory diffs before committing to keep them honest

git diff docs/project_notes/ — read before committing; fix anything misleading.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
/project-memory	subcommand: init\|add-bug\|add-decision\|add-fact\|log-issue	Bootstrap the files and record new entries	0

Cost & Limits

What this costs to run

API quota: None
Tokens per call: Depends on how much of the four files Claude loads; keep entries short
Monetary: Free
Tip: Prefer short, dated entries over long narratives — Claude scans them every session, so size matters.

Security

Permissions, secrets, blast radius

Credential storage: Explicitly: key_facts.md is for non-sensitive config only. Keep secrets in env or a vault, not here.

Data egress: Local files; no network activity from the skill itself

If you commit docs/project_notes/ to a public repo, remember Claude may have recorded internal details — review before pushing.
Don't let agents auto-append to decisions.md without review; that's where stale or wrong context corrodes the whole system.

Troubleshooting

Common errors and fixes

/project-memory command not recognized

Skill not installed at the expected scope. Reinstall with skilz and restart Claude.

Verify: ls ~/.claude/skills/project-memory/ or .claude/skills/project-memory/

Claude ignores decisions.md

Ensure decisions.md has clear ADR-style entries with 'Decision' and 'Rationale' headers; vague bullet points get skimmed over.

Verify: head docs/project_notes/decisions.md

Files keep growing

Archive quarterly — move old entries to docs/project_notes/archive/ so the active files stay scannable.

Verify: wc -l docs/project_notes/*.md

Alternatives

project-memory vs others

Alternative	When to use it instead	Tradeoff
memory-bank-mcp	You want cross-project memory accessible by tool, not files	More flexibility, less visible in PR reviews
codebase-memory	You want a symbol graph of the code, not narrative notes	Different layer of memory
marm-systems	You want a more elaborate memory framework	Heavier setup

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills