project-mem-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

An MCP server + Claude Code plugin that manages persistent project memory files (MEMORY.md) for AI agents. Built with FastMCP 3.x and Python 3.11+.

The MCP server lives in src/project_mem_mcp/server.py. The plugin layer adds auto-read hooks and a dream (consolidation) system.

Development Commands

# Setup
python -m venv venv
source venv/bin/activate
pip install -e .

# Run the server locally
project-mem-mcp
project-mem-mcp --allowed-dir /path/to/projects

# Run without installation (via uvx)
uvx project-mem-mcp

# Plugin installation (in Claude Code)
# /plugin marketplace add /path/to/project-mem-mcp
# /plugin install project-mem@cc-plugin-project-mem

There are no tests or linting configured in this project.

Architecture

MCP Server (src/project_mem_mcp/server.py)

Four MCP tools:

Tool	Purpose
get_project_memory	Read MEMORY.md — full file, head_only TOC, or offset/limit chunk
search_project_memory	Substring search; returns matching lines with 1-indexed line numbers
set_project_memory	Overwrite the entire MEMORY.md
update_project_memory	Apply a single SEARCH/REPLACE patch to MEMORY.md

Security model: Project paths are validated against --allowed-dir arguments. If none are provided, the server defaults to the current working directory.

Patch format: update_project_memory uses a custom SEARCH/REPLACE block format (not unified diff). The search text must appear exactly once in the file; non-unique matches raise ValueError. Only one block per call is allowed.

File-sourced full rewrite (since 0.4.13): set_project_memory accepts the new content from exactly one of two sources — project_info (literal Markdown text) or project_info_file (absolute path to a UTF-8 file the server reads itself). The file path form exists because the consolidator drafts the shrunk memory in a scratchpad file anyway (to iterate and measure size); handing over the path avoids re-emitting tens of KB as a tool parameter, making the dream writeback near-zero output. Validation: absolute path, regular file, valid UTF-8, non-empty (an empty draft would blank the memory — rejected). The path is deliberately NOT restricted to --allowed-dir (the draft lives in a session scratchpad outside the project); the server runs locally with the agent's own privileges, so this adds no access the agent lacks.