kaaustubh/project-memory-mcp

A small, local MCP server that gives AI agents
(Claude Code, Cursor, VS Code / GitHub Copilot, …) a shared, persistent memory of the projects in a code folder —
what each project is, decisions made, and **every bug/issue faced during development.**
It is **stateless**: every tool reads/writes plain files on disk, so multiple clients
(and multiple machines) share one source of truth.
The model
| Layer | Lives in | Auto-loaded into context? | For |
|---|---|---|---|
| Project memory | /AGENTS.md | ✅ yes (via CLAUDE.md → @AGENTS.md) | identity, stack, run cmds, concise decisions/learnings — **keep lean** |
| Issue log | /issues.jsonl | ❌ no | high-volume bug/issue history — fetched on demand |
**Design rule:** durable, low-volume facts go in AGENTS.md (auto-loaded). High-volume
history (bugs) goes in issues.jsonl (queried via search_issues). This keeps the
always-loaded context small while keeping everything searchable.
Works even where MCP is locked down
Some orgs disable third-party MCP servers via policy (e.g. GitHub Copilot's
MCP allowlist enforcement).
Because the memory is **plain files, not a service**, the core value survives that:
- **The memory itself is just files.** AGENTS.md is auto-loaded by the editor reading it —
no MCP call involved — so a project's identity, decisions, learnings, and preferences still
land in the agent's context.
- **The policy is Copilot-scoped and per-client.** It doesn't affect the same server in
Claude Code or Cursor, and orgs running *allowlist / registry-only* mode can permit it —
this server is published to the official MCP Registry (io.github.kaaustubh/project-memory-mcp).
Only the interactive **tools** (log_issue, search_issues, …) go over the MCP channel; the
file-based memory keeps working without it.
Tools
- list_projects, get_project, search_memory — read project memory
- append_decision, append_learning — append a dated bullet to AGENTS.md
- remember_preference — turn a correction / stated habit into a remembered pattern (## Preferences in the root AGENTS.md for a global habit, or a project's for a local one); rides the auto-load, so it comes back next session
- log_issue — record a bug/problem → issues.jsonl
- search_issues — "have we hit this before?" across all projects (field-scoped; optional tags filter)
- list_open_issues, resolve_issue — track / close bugs
- sync_registry — reconcile the root AGENTS.md projects table with what's on disk (adds rows for new projects, flags stale ones)
- find_by_file — given a file path, surface the issues + decisions/learnings that touch it ("why is this code like this?")
- start_initiative, get_initiative, list_initiatives, update_initiative — track a named, multi-session effort (a codename, a plan, an evolving todo list) so it's resumable from any future session by name, not just within the one that started it; see **Initiatives** below
- check_in, check_out — stamp the start/end of the working day and record a standup summary composed from evidence harvested off disk (git commits across every repo, uncommitted WIP, memory writes, initiative progress); the next morning's check_in hands the summary back — that's your standup. Print it any time, no agent needed: npx -y @kaaustubh/project-memory-mcp standup
> You don't call these directly — you talk to your agent in natural language and it picks
> the tool. See **Using it day to day** below for what to actually say.
Using it day to day
Most of it runs itself: opening a project auto-loads its AGENTS.md (the agent already
knows the project), and capture is proactive (plus the optional Stop hook). Your job is
mainly to **pull** memory at the right moments. Just talk to your agent:
| When | Say something like | What fires |
|---|---|---|
| **Before debugging anything** | *"Have we hit this before? "* | search_issues across all projects |
| **Starting something you've done elsewhere** | *"How did I do Stripe webhook verification in any project?"* | search_memory (cross-project) |
| **Landing on confusing code** | *"Why is index.js like this? Check the memory."* | find_by_file |
| **You made a real decision / fixed a real bug** | *(nothing — it logs on its own and tells you)* | append_decision / log_issue |
| **You correct how the agent works** | *"No, always run the typecheck before committing — remember that."* | remember_preference (global or per-project) |
| **Triage** | *"What's still open across my projects?"* | list_open_issues |
| **A bug is fixed** | *"Resolve pulse_stripe-004 — fixed by …"* | resolve_issue |