projectmem in 2026: Give Local Coding Agents Persistent Memory with MCP

If you use an AI coding agent for more than a few sessions, you eventually hit the same frustrating loop: yesterday you fixed a bug, today the agent proposes the same failed fix again. Git remembers what changed, but it does not normally remember why you changed it, what you tried first, or which approach you already rejected.

projectmem is a small local-first tool built around that missing layer. It records issues, attempts, fixes, decisions and notes in a project-local memory store, then exposes that memory to AI coding clients through MCP. The useful part is not “AI memory” in the abstract; it is the ability to surface previous failures before an agent edits the same fragile file again.

This guide shows how to install projectmem 0.3.3, connect it to an MCP-capable coding agent, verify that memory is actually being used, understand the one-server/many-project model introduced in 0.3.0, and keep the local memory safe.

Why projectmem is different from chat history

Chat history is usually a record of conversations. projectmem is a record of development events: an issue happened, an approach was attempted, a fix worked or failed, and a decision was made. Its MCP interface can expose those events as structured tools instead of asking the model to reread an entire transcript.

projectmem is therefore complementary to a coding-agent workflow rather than a replacement for Git or an agent harness. GyanAangan already covers local coding-agent workflows with Cline CLI, SDK and Kanban and local agent setup with OpenHands + Ollama; projectmem adds the persistent project-memory layer underneath those workflows.

What you need

• Python 3.10 or newer.
• Git for projects where you want automatic development-event tracking.
• An MCP-capable AI coding client. The project documents integrations for clients including Claude Code, Claude Desktop, Cursor, Antigravity and Codex.
• A local project you are comfortable modifying while testing.

projectmem does not require a cloud account or a hosted database. Its core memory is stored locally. The current 0.3.x line also supports a shared MCP server that can serve multiple registered projects.

Install projectmem

The official project currently lists version 0.3.3 as the latest release. Install or upgrade it with:

python -m pip install -U projectmem

Then verify the CLI:

pjm --version

If your shell cannot find pjm, check that your Python user or virtual-environment binary directory is on PATH. You can also invoke the module through the Python environment where projectmem was installed.

Initialize one repository

Move into a project you want the agent to remember:

cd ~/Developer/my-project
pjm init

The initialization creates the project's .projectmem/ memory area and installs the project's tracking hooks. The exact generated files can change between releases, so treat pjm init as the source of truth rather than copying an old directory layout from a tutorial.

Now run:

pjm doctor

The doctor command is particularly useful because an MCP server can be correctly installed but still point at the wrong project or an outdated client configuration. In projectmem 0.3.2 and later, pjm doctor also checks client configuration and reports projects that are registered or missing from the project registry.

The important change in projectmem 0.3.0: one MCP server, many projects

Older projectmem configurations could be tied to one repository. Version 0.3.0 introduced a project registry and a shared MCP mode. That means you can configure one MCP server and register multiple repositories instead of creating one server definition per repository.

First discover projects:

pjm doctor

Register discovered projects automatically:

pjm doctor --fix

Or register a specific project:

pjm project register "/Users/you/Developer/my-project"

Inspect the registry:

pjm project list

This is a meaningful distinction for developers who use several repositories. The MCP client only needs one projectmem server entry, while the server can select the project through its project-aware tools.

Connect the MCP server

The official project provides a generic MCP configuration using the Python executable that contains projectmem:

{
  "mcpServers": {
    "projectmem": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "projectmem.mcp_server"]
    }
  }
}

Do not blindly paste /absolute/path/to/python. Replace it with the interpreter from the environment where projectmem is installed. A reliable way to find it on Unix-like systems is:

which python
python -c "import sys; print(sys.executable)"

On Windows:

where python
python -c "import sys; print(sys.executable)"

After changing an MCP configuration, fully restart the client. MCP servers are normally loaded during client startup; editing the configuration while the application is already running does not prove that the new server was loaded.

Verify the MCP connection instead of assuming it works

A successful pip install is not enough. Verify in layers:

1. Run pjm --version.
2. Run pjm doctor inside the project.
3. Confirm the MCP client has a projectmem server entry.
4. Completely restart the MCP client.
5. Ask the client to call the project's memory tools.
6. Use pjm doctor again after configuration changes.

The current projectmem MCP surface includes read-side tools such as get_summary(), get_project_map(), precheck_file(path), search_events(query) and get_context(tokens, focus). Write-side tools include log_issue, record_attempt, record_fix, add_decision and add_note.

A useful first-session instruction is to ask the agent to load the project instructions, summary and project map before making changes. For example:

Before changing code, inspect the projectmem memory for this repository.
Load the project instructions and summary, check the project map, and
precheck the files you plan to edit. If previous failed approaches are
recorded, explain them before proposing a new fix.

The goal is not to force a particular prompt forever. Once the MCP integration is functioning, the agent can discover the available tools and instructions itself.

Test the “don't repeat the failed fix” workflow

Create a small, harmless test case or use a real issue you already understand. Record an issue:

pjm log-issue "API returns 404 after moving the endpoint" --location src/api/routes.py

Then record an attempt and its outcome. The exact CLI help is the safest reference for command spelling because subcommands can evolve:

pjm --help
pjm --help | grep -E "issue|attempt|fix|decision|note"

You can also let the MCP tools perform the structured writes from the coding agent. After a failed attempt, the important distinction is that the failure becomes a durable project event rather than disappearing when the chat session ends.

Before editing a known-problem file, ask the agent to use precheck_file. If the file has a relevant failed approach, the agent should see that history before making another change.

Memory gets stale — and projectmem deliberately does not hide that

Persistent memory is useful only if you can tell when it is old. projectmem's current design includes stale-memory detection. A decision or fix associated with a file can be flagged when the file has moved on in Git history or no longer exists.

This is important because a memory system that blindly repeats yesterday's advice can become another source of bugs. projectmem's model is to flag stale knowledge rather than silently delete it.

For a refactor sprint where warnings become noise, projectmem also documents a bounded precheck snooze rather than telling developers to permanently disable verification:

pjm precheck --snooze 2h

When the period expires, normal checks can resume. Treat this as a workflow control, not as a substitute for reviewing an important warning.

Privacy and security: local does not mean automatically safe

projectmem's design is local-first. The project states that memory is stored locally and that normal operation does not require a cloud service or telemetry. Optional update checking can be enabled separately.

But the memory itself can contain sensitive engineering information: internal paths, architecture decisions, error messages, failed security fixes and notes about infrastructure. If you commit distilled projectmem files to Git, you are intentionally sharing that knowledge with anyone who can read the repository.

For a private repository, decide whether the team wants shared memory. For a highly sensitive repository, the project's documented option is to add the entire .projectmem/ directory to .gitignore.

Also remember that MCP gives an AI client a new tool surface. Keep the same permission discipline you would use for any local agent. Do not assume that because the memory is local, every connected model or MCP client is automatically trusted.

This is especially relevant when combining projectmem with broader MCP workflows. GyanAangan's MCP 2026 guide covers the protocol-level migration and security considerations, while the Goose MCP security guide covers permissions and prompt-injection risks in a local agent.

projectmem vs putting everything in AGENTS.md

In other words, keep stable rules stable and let projectmem capture the changing story of development.

When projectmem is worth adding

• You run coding agents across multiple days or weeks.
• You frequently debug the same files or subsystems.
• You use multiple AI clients against the same repository.
• Your team wants useful agent knowledge to survive individual chat sessions.
• You want local project memory without adding a hosted vector database.

When it may be unnecessary

• You only use an AI assistant for short one-off edits.
• Your project is tiny and its rules fit comfortably in normal documentation.
• You do not want development-event metadata stored alongside the project.
• Your team has not decided which agent-generated information is safe to share.

There is also no reason to install another MCP server simply because it exists. If your current agent workflow is stable and you rarely repeat debugging work, the extra tool surface may not justify the maintenance.

Troubleshooting checklist

“The CLI works but my agent cannot see projectmem”

Check the MCP command's Python path, restart the client completely, and run pjm doctor. A valid Python installation with projectmem installed is not proof that the MCP client is launching that same interpreter.

“The agent sees the server but the wrong project”

Check the project registry and whether the MCP configuration is still pinned to an old single-project root. Run pjm project list and pjm doctor. Shared mode makes project selection explicit; do not rely on a guessed working directory when several repositories are registered.

“The agent keeps repeating an old fix”

Verify that the issue/attempt/fix was actually recorded and that the client can call precheck_file or search the memory. Then inspect whether the memory has become stale because the file changed substantially.

“Windows behaves differently”

Upgrade rather than debugging an old tutorial first. The 0.3.2 and 0.3.3 releases specifically include Windows configuration/watch and console-output fixes, and the 0.3.3 release notes report verification on Windows 11 with Python 3.12.10 and Git 2.54.0.

A practical local-agent stack

projectmem makes the most sense as one layer in a larger local development workflow. For example, you can combine a local model runtime such as Ollama with a coding agent, MCP tools for external capabilities, and projectmem for durable project memory. GyanAangan's Goose + Ollama setup is useful for the agent/runtime layer, while the Ollama security guide covers model and network hardening.

The architecture is simple:

Local model/runtime
       ↓
Coding agent
       ↓
MCP tools ───────── projectmem
       ↓                 ↓
Code / shell / APIs    Project memory
                         ↓
                issues → attempts → fixes
                         ↓
                  precheck before edits

The benefit is not that projectmem makes a model smarter. It gives the agent a durable record of what the project already learned.

FAQ

Does projectmem replace Git?

No. Git remains the source of truth for code history. projectmem records development context that Git normally does not: failed approaches, decisions, gotchas and the reasoning around fixes.

Does projectmem require a vector database?

No. Its current architecture uses local files and structured event data rather than requiring a hosted vector database. Its MCP layer provides focused retrieval tools.

Can I use it without an MCP client?

Yes. The project also documents Markdown-based instruction surfaces. MCP is the richer integration because an agent can query structured memory and precheck files directly.

Is it cloud-based?

The project's design is local-first and does not require a cloud account. Optional update checking is separate and opt-in.

What is the current version?

At the time of writing, the official GitHub releases page lists projectmem v0.3.3 as the latest release, dated September 15, 2026.

Official sources

• projectmem official GitHub repository
• projectmem releases and changelog
• projectmem official website
• PROJECTMEM research paper on arXiv

Bottom line

If your local coding agent feels “smart today, forgetful tomorrow,” the missing piece may not be a larger model. It may be durable project memory. projectmem takes a deliberately narrow approach: record what happened during development, expose it through MCP, and warn the agent before it repeats known mistakes.

That makes it particularly interesting for long-running local-agent workflows where Cline, Goose, OpenHands, Codex or another MCP-capable client repeatedly touches the same codebase. Start with one repository, run pjm doctor, connect the MCP server, verify a real precheck, and only then decide whether the memory layer is useful enough to keep.