project-memory MCP server

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

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:

The one habit that matters: make "have we hit this before?" reflexive before every debugging session. That's where a memory tool earns its keep; the rest the system handles.

Capture is confirming, not silent — when the agent logs something it tells you in one line. Correct it freely: "don't log that", or "actually, log this too."

Escape hatches: PROJECT_MEMORY_HOOK=off silences the Stop hook for one session; uninstall-hook removes it entirely.

Install (npm — recommended)

From your code/projects folder, run:

cd ~/code            # the folder that holds your projects
npx -y @kaaustubh/project-memory-mcp install

That registers the server, using the current directory as your projects root, with every client that has an MCP config location on this machine:

Each write merges into the existing file (other MCP servers you've already configured are left alone) and is independently best-effort — a client that isn't installed on this machine is silently skipped, the rest still get registered. Restart whichever app(s) you use, then ask your agent "set up project memory for this folder" to scaffold AGENTS.md for each project.

Copilot surfaces (VS Code, CLI, JetBrains, Visual Studio): tools only run in Agent mode, and config changes need a restart to take effect.

No clone, no global install — the MCP config just runs npx, which fetches and runs the latest version on demand.

Team memory (beta signup): want this memory shared across your team instead of just your machine? Register your interest: https://github.com/kaaustubh/project-memory-mcp/issues/1

From source instead

git clone https://github.com/kaaustubh/project-memory-mcp.git ~/code/.memory-server
cd ~/code/.memory-server && ./install.sh

How it works (after install)

A common question: "once I install it, does it just start doing things?" Not quite — the server is passive. Here's the actual flow:

1. Restart your editor. MCP servers are loaded at startup, so the server only becomes available the next time you launch Claude Code / Cursor / VS Code.
2. Push layer (automatic, not the server): when you open a project, the editor reads AGENTS.md (via CLAUDE.md → @AGENTS.md) into the model's context for you. This is why the agent "just knows" what your project is — it's a built-in editor feature.
3. Pull layer (the server, on request): the server announces its tools and then waits. It does nothing on its own. The agent calls a tool only when it's relevant — e.g. you say "log this bug" or "have we hit this before?", or the model decides a tool is useful. There's no background process or scanning.

Day one is empty. A fresh setup has no AGENTS.md files yet, so the auto-load has nothing to load and log_issue will refuse until a project's memory exists. Bootstrap once by asking your agent: "set up project memory for this folder" — it creates the AGENTS.md files. After that, everything works.

In short: a convention (auto-loaded files) + a tool the agent chooses to use + a one-time setup. No magic, no daemon.

Proactive capture (you don't have to say "log this")

The server ships a standing capture policy (sent to the client on connect, plus directive tool descriptions), so the agent records things on its own instead of waiting for you to ask:

• Before debugging a reported error → it checks search_issues for a prior fix.
• After fixing a non-trivial bug → it calls log_issue.
• After a real decision or a durable gotcha → append_decision / append_learning.
• After you correct how it works or state a habit → remember_preference, so the one-time correction becomes a pattern it brings back next session.

It's proactive but not silent: the agent tells you in one line what it recorded, asks when unsure rather than logging noise, and skips trivia and secrets. You can always override — "log this", or "don't bother". The standing policy is best-effort (it depends on the model following it); for a hard guarantee, add the opt-in Stop hook below.

Guaranteed capture (opt-in Stop hook)