/ Directory / Playground / project-memory
← All servers ↗ GitHub
● Community SpillwaveSolutions ⚡ Instant

project-memory

by SpillwaveSolutions · SpillwaveSolutions/project-memory

Four human-readable files — bugs.md, decisions.md, key_facts.md, issues.md — that Claude reads before proposing changes. Project memory without a database.

project-memory is a Claude Code skill that installs four lightweight notes under docs/project_notes/ and teaches Claude to consult them before making architectural changes. Unlike memory-bank MCPs, it's plain files you review in PRs: bugs.md captures error patterns with prevention strategies, decisions.md is your ADR log, key_facts.md holds non-sensitive config, and issues.md is a work log. Installable globally, per-project, or per-workspace.

▶ Watch demo 📦 Install 💡 Use Cases

Why use it

Key features

Live Demo

What it looks like in practice

project-memory-skill.replay ▶ ready
0/0

Install

Author repository · Claude Skills documentation

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
  1. Install at project scope
    pip install skilz && skilz install SpillwaveSolutions_project-memory/project-memory --scope project✓ Copied
    → .claude/skills/project-memory/SKILL.md appears
  2. Run the bootstrap command
    /project-memory — initialize the four files for this repo.✓ Copied
    → docs/project_notes/ created with the four canonical files
  3. 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
  1. 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
  1. Make sure the decision is in decisions.md
    Record: 'We use Repository pattern, not Active Record. Rationale: <x>.'✓ Copied
    → Clear ADR in decisions.md
  2. 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

ToolInputsWhen to callCost
/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

Troubleshooting

Common errors and fixes

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

AlternativeWhen to use it insteadTradeoff
memory-bank-mcpYou want cross-project memory accessible by tool, not filesMore flexibility, less visible in PR reviews
codebase-memoryYou want a symbol graph of the code, not narrative notesDifferent layer of memory
marm-systemsYou want a more elaborate memory frameworkHeavier setup

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills

Continue exploring

Related tools and workflows

Choose another guide for your workflow, or explore a collection.

Browse all topic collections → · See 29 new official additions →