Project Memory MCP

An MCP server and Claude Code plugin for persistent project memory. Allows AI agents to maintain knowledge about projects between conversations via MEMORY.md files.

Features

• Store & retrieve project knowledge in Markdown format
• Incremental updates via SEARCH/REPLACE patches
• Auto-read hook — automatically loads project memory on first prompt (Claude Code plugin)
• Dream consolidation — automatic project memory cleanup and deduplication (Claude Code plugin)

Installation

Claude Code Plugin (recommended)

Installs the MCP server, auto-read hook, and dream consolidation:

/plugin marketplace add /path/to/project-mem-mcp
/plugin install project-mem@cc-plugin-project-mem

Standalone MCP Server

For Codex, Claude Desktop, Cursor, or other MCP clients:

uvx project-mem-mcp

MCP Client Configuration

{
  "mcpServers": {
    "project-mem-mcp": {
      "command": "uvx",
      "args": [
        "project-mem-mcp",
        "--allowed-dir", "/path/to/your/projects"
      ]
    }
  }
}

The --allowed-dir argument restricts which directories the server can access. Can be used multiple times. Defaults to the current working directory if omitted.

Install from Source

git clone https://github.com/pynesys/project-mem-mcp.git
cd project-mem-mcp
python -m venv venv
source venv/bin/activate
pip install -e .

Tools

get_project_memory

Retrieves MEMORY.md content. With no extra args, returns the whole file. The server raises ValueError if the file would exceed ~20K estimated tokens (below most clients' tool-result caps); use head_only or offset/limit to pull what you need.

get_project_memory(
    project_path: str,
    offset: int = 0,           # 1-indexed start line; 0 = from start
    limit: int | None = None,  # max lines to return
    head_only: bool = False,   # return only size + heading TOC
) -> str

Typical large-file pattern: call once with head_only=True to get size and a section TOC (line ranges), then fetch sections via offset/limit.

search_project_memory

Substring search inside MEMORY.md. Case-insensitive. Returns matching lines with 1-indexed line numbers; combine with get_project_memory(offset, limit) to fetch surrounding context for a hit.

search_project_memory(
    project_path: str,
    query: str,
    max_results: int = 50,
) -> str

set_project_memory

Overwrites the entire MEMORY.md. Use when creating a new project memory or when patches fail.

set_project_memory(
    project_path: str,
    project_info: str | None = None,
    project_info_file: str | None = None,
)

Content comes from exactly one of the two sources: project_info is the literal Markdown text; project_info_file is an absolute path to a UTF-8 file the server reads itself — preferred for large rewrites drafted to a file, since the content need not be re-emitted as a parameter. Parameters are never shell-expanded, so $(cat draft.md) inside project_info does not work (the server rejects payloads that look like unexpanded substitutions).

update_project_memory

Applies a single SEARCH/REPLACE patch to MEMORY.md:

update_project_memory(project_path: str, patch_content: str)

Patch format:

<<<<<<< SEARCH
Text to find in the project memory file
=======
Text to replace it with
>>>>>>> REPLACE

The search text must appear exactly once in the file. Use empty replacement to remove content.

Plugin Features

When installed as a Claude Code plugin, you also get:

Project-memory Skill (auto-trigger)

Guides Claude on when and how to save to project memory. Automatically triggers when insights worth persisting are discovered — architecture decisions, gotchas, non-obvious patterns, current work context. The skill is marked user-invocable: false so it does not appear in the slash command picker; the main model invokes it autonomously.

Auto-read Hook

Automatically reads MEMORY.md into context on the first prompt of each session. No manual tool call needed.

Dream Consolidation

Automatic project memory maintenance triggered after writes when:

• File size exceeds 50KB
• Last consolidation was more than 24 hours ago

The dream spawns a sonnet subagent that:

• Removes content duplicated in CLAUDE.md files
• Restructures for clarity and LLM readability

No backup is written; use git to recover the pre-dream state if needed.

Manual trigger: /dream

The last-dream timestamp is stored as last_dream: inside a YAML frontmatter block at the top of MEMORY.md. Projects previously using this plugin may still have a .claude/.last-dream-timestamp file — that file is now ignored and can be safely deleted (the first dream run after upgrade repopulates the frontmatter).

Security

• Project paths are validated against --allowed-dir arguments
• Project memory files should never contain sensitive information
• Project memory files must be in English

Dependencies

• fastmcp (>=3.2.0, <4.0.0)

License

MIT