memory-mcp

memory-mcp is a small, local Model Context Protocol server for a user-owned Git repository of durable memory. It gives agents reliable mechanisms to list, read, search, inspect history and diffs, capture unstructured text, or submit bounded changes for review.

The repository is the product's durable state. memory-mcp is merely an interface to it.

It is deliberately not a database, ontology, knowledge graph, hosted service, agent, or automatic consolidation system. Markdown remains readable without this program. Git provides history, provenance, rollback, and the basis for future transactions. The agent—not the server—decides what a note means and how it should be organised: mechanism below, intelligence above.

┌──────────────┐
│  AI agent    │
└──────┬───────┘
       │ MCP
┌──────▼───────┐
│  memory-mcp  │
│              │
│ mechanisms   │
└──────┬───────┘
       │ filesystem + Git
┌──────▼────────┐
│ memory repo   │
│               │
│ Markdown      │
│ Git history   │
└───────────────┘

Architecture

The Python core and each running server instance are bound to exactly one configured repository root. It validates repository-relative paths and provides dependency-light filesystem and Git operations. A thin adapter exposes those operations as MCP tools over stdio. Read-only and capture modes make no network requests and send no telemetry. Pull-request mode deliberately uses Git and a configured forge provider to refresh reviewed memory and publish proposals.

Installations that use more than one memory repository should configure a separate MCP server instance for each repository. The MCP client gives each instance a distinct name and starts it with that repository's own MEMORY_MCP_REPOSITORY and, where appropriate, MEMORY_MCP_MODE. This keeps repository selection and permissions at the MCP configuration boundary rather than adding routing or cross-repository operations to memory-mcp.

The memory repository may use any layout. Names such as projects/, principles/, or inbox/ carry no protocol meaning. V1 understands only a repository, relative paths, text files, and Git changes.

Python 3.11+ was chosen for its mature standard-library filesystem, subprocess, atomic-file, and testing support. The official MCP SDK is the sole runtime dependency. Text search is implemented locally in Python, so ripgrep is not required. Git must be installed.

Related MCP server: Engram

Install and configure

Using uv:

git clone https://github.com/credp/memory-mcp.git
cd memory-mcp
uv sync

Create or choose a separate Git repository for memory:

mkdir -p "$HOME/Projects/memory"
git -C "$HOME/Projects/memory" init

Set MEMORY_MCP_REPOSITORY in the process environment to that repository's root. Do not put a private absolute path in a committed configuration file.

The server defaults to read-only mode. In this mode it does not register or advertise any tool capable of changing the memory repository. To deliberately enable new-file capture, set MEMORY_MCP_MODE=read-write. To use reviewed contributions instead, set MEMORY_MCP_MODE=pull-request. Any other value is rejected, so a typo cannot accidentally enable writes.

An MCP client configuration commonly looks like:

{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": ["--directory", "/path/to/memory-mcp", "run", "memory-mcp"],
      "env": {
        "MEMORY_MCP_REPOSITORY": "/path/to/private/memory"
      }
    }
  }
}

The exact outer configuration format varies by client. For a global install, uv tool install . provides the memory-mcp command.

Updating the memory repository

General memory updates may happen through ordinary filesystem and Git tools, or through the optional pull-request workflow. In either case, the Git repository remains the source of truth.

The only current MCP write mechanism is the optional capture tool, which is available when a server instance is explicitly configured with MEMORY_MCP_MODE=read-write. Capture only creates a new untracked Markdown file and is not a general editing or repository-maintenance interface. In the default read-only mode, all updates must happen outside the MCP server.

In pull-request mode, refresh fetches and fast-forwards a clean checkout of the configured reviewed branch. propose_memory creates one new Markdown file from that remote base in a disposable worktree, commits only that file, pushes a new branch, and asks the configured provider to open a review. It never approves or merges reviews, never rewrites history, and refuses a dirty primary checkout or an existing destination path.

GitHub is the first provider. It uses the gh CLI and its existing authentication, so install gh and authenticate the service identity before starting the server. For unattended deployment, give that identity only the repository permissions needed to read contents, push proposal branches, and open pull requests. Supplying and rotating a GitHub App installation token is an operator concern; do not put it in the memory repository or MCP arguments. GitLab can be added as a separate provider without changing the proposal service or MCP contract.

{
  "MEMORY_MCP_MODE": "pull-request",
  "MEMORY_MCP_REPOSITORY": "/path/to/private/memory",
  "MEMORY_MCP_PROPOSAL_PROVIDER": "github",
  "MEMORY_MCP_PROPOSAL_REMOTE": "origin",
  "MEMORY_MCP_PROPOSAL_BASE_BRANCH": "main",
  "MEMORY_MCP_PROPOSAL_BRANCH_PREFIX": "memory-proposal"
}

Protected local service

When Codex must not inherit the GitHub credential, install pull-request mode as a persistent loopback service under a separate Unix identity. This installer is Linux/systemd-specific. It requires an existing clean checkout on main, a credential-free https://github.com/... origin, the gh CLI, and root access.

Create a fine-grained PAT restricted to the memory repository with repository permissions Contents: read and write and Pull requests: write. Then run:

sudo "$(command -v memory-mcp-service)" install home-operations \
  --repository /srv/memory/home-operations \
  --port 8771 \
  --take-ownership

The ownership flag is deliberately mandatory because the installer recursively transfers the checkout to the dedicated memory-mcp-home-operations service account. The installer prompts for the PAT without echo; it never accepts the token in command-line arguments. It stores the source credential at /etc/memory-mcp/home-operations/github_pat with root-only permissions and passes it to the service through systemd's credential mechanism. It also installs a root-owned pre-push hook and forces the service to use it; the hook rejects deletions, tags, main, and every branch outside memory-proposal/*. This is a local mistake-prevention control, not a substitute for server-side branch protection against a stolen PAT.

The command prints the corresponding Codex registration command:

codex mcp add home-operations --url http://127.0.0.1:8771/mcp

Codex knows only the loopback MCP address. The PAT, writable checkout, GitHub CLI and outbound provider access remain in the separate service process. Any local process able to reach that loopback port can invoke the bounded MCP tools, so use host firewall rules when local users require different tool access.

Review the generated unit without installing anything:

memory-mcp-service print-unit home-operations \
  --repository /srv/memory/home-operations \
  --port 8771

Rotate the PAT without putting it in shell history:

sudo "$(command -v memory-mcp-service)" rotate-token home-operations

Remove the service and credential while deliberately preserving the repository:

sudo "$(command -v memory-mcp-service)" uninstall home-operations

Uninstall leaves the dedicated service account and repository ownership intact so it cannot orphan repository files under a deleted numeric UID. Reassign or remove those explicitly after preserving any required Git work.

Codex

Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share MCP configuration on the same host. With this repository checked out locally, add the server from a shell as follows, replacing the memory path if necessary:

cd /path/to/memory-mcp
uv sync
codex mcp add memory \
  --env MEMORY_MCP_REPOSITORY="$HOME/Projects/memory" \
  -- uv --directory "$PWD" run memory-mcp

Use an absolute path for the memory repository. The shell expands $HOME and $PWD before Codex stores the configuration. Confirm the result with:

codex mcp list

Restart Codex after adding or changing the server. In the Codex terminal UI, /mcp shows the active MCP servers and their tools.

Tell Codex about persistent memory

The server advertises its purpose through the MCP instructions field, but a small global Codex instruction makes the intended relationship explicit: this repository is the user's persistent context across agents, chats, and projects, not merely a tool to use when working on memory-mcp itself.

Add the following boilerplate to $CODEX_HOME/AGENTS.md. CODEX_HOME defaults to ~/.codex, so the usual location is ~/.codex/AGENTS.md:

## Persistent memory

A user-owned persistent memory is available through the `memory` MCP.

Use it as the primary place to read or store durable context relevant to the
user's request, including prior decisions, preferences, constraints, projects,
and historical reasoning.

Search memory when existing context could materially improve the task. Do not
assume every request requires memory.

Treat retrieved memories as supporting context, not unquestionable truth.
Prefer reviewed/current material over inbox, candidate, or historical material.

Store information only when it is likely to remain useful across future agents
or conversations. Do not store credentials, secrets, or sensitive information
unless the user explicitly requests it.

Codex reads this global file before project-level AGENTS.md files. If $CODEX_HOME/AGENTS.override.md exists and is non-empty, Codex uses it instead of the global AGENTS.md; put the boilerplate there as well, or remove the override, if the memory guidance is not being loaded. Start a new Codex session after changing the file because the instruction chain is assembled once per run.

This is intentionally a relevance rule, not a requirement to load memory at the start of every session. Codex should consult memory when it can improve the user's task and leave it alone for self-contained requests.

To update a source-checkout installation when this upstream repository gains new commits:

cd /path/to/memory-mcp
git pull --ff-only
uv sync
uv run pytest

Then restart Codex so it launches the updated server. The MCP configuration does not need to be added again because it continues to point at the checkout. git pull --ff-only deliberately stops instead of creating an implicit merge if the local branch and upstream have diverged; review or preserve local work before resolving that situation.

Tools

• list_memories(path="", recursive=false) lists directory entries. .git internals are excluded.

• read_memory(path) reads a bounded, valid UTF-8 text file and returns relative-path metadata.

• search_memories(query, path="", case_sensitive=false, limit=100) performs deterministic literal line search. Oversized and malformed files are skipped.

• history(path="", limit=20) returns bounded Git history with commit, timestamp, author, and subject.

• diff(path="") returns tracked working-tree changes against HEAD and separately lists untracked files. In an unborn repository it reports the staged diff.

• capture(content, destination="") is available only in explicit read-write mode. It writes the content unchanged (apart from ensuring a final newline) to a new Markdown file. destination is a configurable, existing relative directory; the neutral default is the repository root. Creation uses an exclusive filename and does not stage or commit anything.

• refresh() is available only in pull-request mode. It requires a clean checkout on the configured base branch, fetches that branch, and applies only a fast-forward update.

• propose_memory(path, content, title, rationale, source_run_id="") is available only in pull-request mode. It accepts a new repository-relative Markdown path, scans all outbound text for common credential shapes, creates an isolated contribution, and returns the review URL and Git provenance.

File reads are limited to 2 MiB, search skips files over 2 MiB, history is limited to 100 commits, and search is limited to 1,000 matches. These conservative v1 bounds keep MCP responses manageable.

Security and privacy

Each MemoryRepository instance is a security boundary. All external paths are relative to its exact Git root. Absolute paths, traversal with .., and symlinks resolving outside the root are rejected. Recursive operations do not follow symlinks, and returned data does not reveal the configured absolute path.

Each server instance exposes one repository and defaults to read-only access. Operators can explicitly opt into read-write capture with MEMORY_MCP_MODE=read-write. Multiple repositories are exposed through separately named MCP server instances, so each repository retains an independent security and permission boundary. A server instance never routes to another repository or performs cross-repository operations.

Repository content stays local in read-only and capture modes. Pull-request mode sends the proposed content, title, rationale, branch, and commit to the Git remote and review provider. There is no external indexing, analytics, or telemetry. MCP clients, agents, Git hosting, and the narrowly scoped service identity are therefore part of that mode's trust boundary.

Capture creates an obvious untracked file with mode 0600. Pull-request mode never resets or discards local work, rewrites history, approves reviews, or merges them. Its contribution branches are intentionally visible on the remote; if review creation fails after a successful push, the branch remains available for diagnosis or manual review rather than being deleted implicitly.

Development

uv sync --extra dev
uv run pytest

Tests create isolated temporary Git repositories and cover listing, reading, literal search, history, diff, capture, dirty trees, spaces, Unicode, traversal, escaping symlinks, missing/non-Git/empty repositories, malformed and oversized files, capture filename collisions, and Git failures.

To prepare a patch release from a clean working tree:

make release

make release defaults to a patch increment (for example, 0.0.2 to 0.0.3); make release BUMP=patch is the explicit equivalent. Use make release BUMP=minor or make release BUMP=major when those larger version increments are intended. The command runs the tests, updates pyproject.toml and uv.lock, creates a release commit, and adds the matching annotated Git tag locally. It prints the separate git push command needed to publish the release.

Roadmap

Phase 1 (implemented): read-only-by-default list, read, textual search, history, and diff; optional explicit read-write capture.

Phase 2 (implemented for new memories): optional GitHub pull-request contributions created in isolated worktrees, with a provider boundary for other forges. Broader edit, rename, and deletion proposals remain future work.

Phase 3: improve support and documentation for multi-memory installations by running one separately named MCP server instance per repository. Each instance remains bound to one repository and has its own access mode; repository routing, discovery, and cross-repository operations remain outside the server.

Possible later experiments include semantic search, local embeddings, related-memory discovery, structured frontmatter, and agent-assisted consolidation. They must remain optional layers; the core will never require them.

The governing design test is simple: if memory-mcp disappeared tomorrow, the user would still own a clean, understandable, useful Git repository containing all memories and history.