projectmem: local coding agent memory that warns before you repeat a failed fix

The problem projectmem targets, and who actually has it

An AI coding agent starts every session with no history of the project. It does not know that the obvious fix for a flaky test was tried three days ago and made things worse, or that a dependency was pinned for a reason. The model is not less capable than last time; it is just amnesiac. projectmem is built for that gap. It records typed events, which the README lists as issues, attempts, fixes, decisions and notes, and stores them in a plain .projectmem/ directory inside the repository. The audience is narrow and specific: developers who already run a coding agent through MCP, who work on the same repository over many sessions, and who have felt the cost of an agent proposing an approach that was already rejected. If you use an agent for one-off scripts in throwaway directories, the problem does not exist for you. The README frames the goal as making the agent experienced rather than smarter, which is a fair description of what an event log can do and what it cannot.

How the memory layer works: typed events, a JSONL file, one MCP server

The architecture is deliberately plain. Events are appended to .projectmem/events.jsonl, and the dashboards are generated locally from that file, as the README states under the pjm visualize screenshot. Because events carry a type, projectmem can do something a chat-history memory cannot: when an agent is about to attempt an approach that matches a recorded failure, it can warn before the attempt rather than after. That is the pre-commit warning shown in the demo GIF. A native MCP server exposes 17 tools to the client, so the agent reads memory at session start and writes back what it learned without a human copying notes between tools. Since version 0.3.0, one server serves every project, which is why the recommended config carries no --root and no cwd. That design choice is the whole reason setup is described as a one-time cost. It is also the source of the most common failure: a client config still pinned to a single repository makes every other project invisible, and the README calls this out explicitly as the thing pjm doctor checks for.

Installing projectmem and logging your first issue

projectmem ships on PyPI and requires Python 3.10 or newer, according to pyproject.toml. The README gives a single install command, and the -U flag matters if you are coming from 0.1.x or 0.2.x, because the server model changed in 0.3.0.

pip install -U projectmem

Next, let the tool find the repositories you already have. pjm doctor looks in places like ~/Developer, ~/code, ~/projects, cloud folders, and every drive on Windows, and lists projects that have memory but are not yet registered.

pjm doctor

Anything it missed can be added by path. Registering a project creates the memory store for it.

pjm project register "/Users/you/Developer/repos/ossdrop"

Then register everything the doctor found in one pass.

pjm doctor --fix

The last step is pointing your client at the server. Run pjm init and it prints the block below with your own Python path filled in. The absence of --root and cwd is intentional and is what lets one server cover all projects.

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

After editing the config you must fully restart the client, because MCP servers only load on a cold start. Run pjm doctor once more. It should report no client pinned to a single repo, which is the state the README calls all green. From then on, per repository, the workflow is pjm init.

Where projectmem stops being the right tool

The memory is only as good as what gets written to it. If your agent does not log attempts, or you work with a client whose MCP support is partial, .projectmem/events.jsonl stays thin and the pre-commit warning has nothing to match against. There is no documented mechanism for importing history from a previous tool, so switching costs you the past. The README does not document rollback or how to undo a bad registration, which is worth knowing before you run pjm doctor --fix across a directory full of unrelated repositories. The tool is also scoped to a repository: it is not a general knowledge base for your whole machine, and the one-server-many-projects design is about routing, not about merging memory across codebases. Finally, the README's claim of saving up to 50% or more of AI tokens is the project's own figure and its own framing; treat it as a target the design aims at, not a measurement you can transfer to your workload.

projectmem compared with general agent memory tools

The topics list puts projectmem next to mem0-alternative, and the distinction is real. A general memory layer tends to store conversational facts and preferences so an assistant can recall them later; the unit is usually a message or a summarized fact. projectmem's unit is a typed engineering event tied to a repository, and its payoff is judgment at the moment of action: the warning that this approach already failed here. That is a narrower product. It will not remember that you prefer terse commit messages, and it will not follow you across unrelated projects. If what you want is a personal assistant that recalls context about you, a general memory tool is the better fit. If what you want is a project that stops making the same mistake, the event log is the right shape, because a failure record only means something in the context of the code it happened in.

Maintenance, releases and what the MIT licence means here

The repository is not archived, and the last push was on 2026-09-07, the same day v0.3.2 shipped. The release history is short and recent: v0.3.0 and v0.3.1 both landed on 2026-09-01, and v0.3.2 followed six days later with Windows support for the file watcher and what the release title calls a doctor that tells the truth. The project is young enough that interfaces can still move, and the 0.3.0 change to a single server is exactly that kind of move. Budget for reading the changelog before upgrading, not just running pip install -U. The runtime dependency set is small: typer, mcp and watchdog, per pyproject.toml, so the surface you are trusting is limited. The licence is MIT, which permits commercial use and modification; if you redistribute projectmem inside a product, the usual obligation is preserving the copyright notice and licence text, and the LICENSE file in the repository is the authoritative copy. That is a description of the terms, not legal advice.

Editorial conclusion

Adopt projectmem if your agent keeps rediscovering the same dead ends across sessions and you want that record to stay in the repository rather than a cloud account. Skip it if you only ever work in one long session, or if you need a hosted memory service with a team UI, because projectmem is a local .projectmem directory plus an MCP server and nothing else. Before committing, install it with pip install -U projectmem, run pjm doctor to see which projects it finds, then pjm doctor --fix to register them, and confirm with pjm doctor that no client is still pinned to a single repo. That last check is the one that decides whether a new project is visible to your agent at all.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. riponcm/projectmem on GitHub