May 6, 2026 4 min read Python fork

mcp memory service

Abstract

Open-source persistent memory for AI agent pipelines (LangGraph, CrewAI, AutoGen) and Claude. REST API + knowledge graph + autonomous consolidation.

Forked from doobidoo/mcp-memory-service

The Problem

AI agents (LangGraph, CrewAI, AutoGen, Claude) lack persistent memory across runs. Each conversation starts from zero—no shared context, no accumulated decisions, no causal knowledge graph. Teams end up gluing together Redis, Pinecone, and custom code to give agents continuity.

What This Does

mcp-memory-service is a self-hosted memory backend for AI agent pipelines. It exposes a REST API, MCP transport, OAuth 2.0 auth, CLI, and a web dashboard. Agents store decisions, share causal knowledge graphs, and retrieve context in ~5ms. The service supports remote MCP for browser-based claude.ai integration.

The repo is a portfolio of 8 self-contained projects, not a single codebase. The substantial ones: src/ (Python core service), claude-hooks/ (Claude Desktop integration hooks), scripts/ (operational tooling), and video/ (demo content).

How It Is Wired

Execution starts in claude-hooks/core/auto-capture-hook.js at main (reaches 69 functions). The traced path: main → loadConfig → fs.readFile — the hook reads config from the filesystem, then captures conversation transcripts via parseTranscript, extractTextContent, and storeMemory.

The Python server entry points are src/mcp_memory_service/server/__main__.py and src/mcp_memory_service/cli/main.py. main calls runTest 37 times, and runAllTests calls runTest 15 times — the test harness is a first-class citizen.

Highest-blast-radius modules:

src/mcp_memory_service/config.py — 42 modules import it; it's in an import cycle. Changing config ripples everywhere.
src/mcp_memory_service/models/memory.py — 41 importers, 0 imports. Pure data model, stable.
src/mcp_memory_service/web/app.py — imports 31 modules (instability 0.94); the web layer is a thin adapter over everything else.

Import cycles exist in config.py, storage/base.py, and storage/sqlite_vec.py. Breaking them requires extracting shared types or deferring imports. The cost: any change to these files risks circular-import failures at runtime.

File map:

src/mcp_memory_service/web/static/app.js — 204 functions; the dashboard frontend
claude-hooks/core/auto-capture-hook.js — 6 functions; captures Claude transcripts, writes files
claude-hooks/utilities/session-tracker.js — 20 functions; session lifecycle, generates secrets, writes files
claude-hooks/utilities/memory-client.js — 19 functions; connects via MCP or HTTP

The 21 filesystem-touching functions and 1 network call are the only external effects; the rest is internal computation.

How To Use It

Setup (from pyproject.toml):

pip install mcp-memory-service
# or
uv pip install mcp-memory-service

Run the server (from README):

MCP_STREAMABLE_HTTP_MODE=1 \
MCP_SSE_HOST=0.0.0.0 \
MCP_SSE_PORT=8765 \
MCP_OAUTH_ENABLED=true \
python -m mcp_memory_service.server

Configuration: copy .env.example to .env and set storage backend, OAuth credentials, and MCP mode. The service supports SQLite (with vector search) and other backends.

Real-World Use

A LangGraph pipeline where agents share memory:

from mcp_memory_service.client import MemoryClient

client = MemoryClient(base_url="http://localhost:8000")
client.store("user-preferences", {"theme": "dark", "timezone": "UTC"})
context = client.retrieve("user-preferences")
# Pass context into the next agent run

Code Health & Issues

Static analysis found 316 findings (69 high, 245 medium, 2 low) across 7 kinds:

High — Import cycle members (9): config.py, storage/base.py, storage/sqlite_vec.py. Circular imports can break at runtime.
High — Deep nesting (28): models/memory.py, storage/base.py, storage/sqlite_vec.py — max depth 6.
High — Oversized files (8): config.py at 782 lines; storage/sqlite_vec.py and storage/base.py similar. High change-ripple.
High — Hub modules (4): config.py (42 dependents), models/memory.py (41), storage/base.py (21). Churn here is wide-blast-radius.
Medium — Broad exception handling (9): bare except in storage/base.py, storage/sqlite_vec.py, __init__.py.
Medium — High branching density: claude-hooks/utilities/context-formatter.js — 371 branch points / 954 lines.
Medium — File without context manager: web/oauth/registration.py — open() not wrapped in with.

SDLC observations from the file structure:

High — Unpinned GitHub Actions: .github/workflows uses @v4/@v6 tags, not commit SHAs. Tag-move attacks leak secrets.
High — Committed .env: archive/configs/.env.sqlite.backup is tracked. Rotate anything it holds.
High — continue-on-error on correctness gates: .github/workflows/docker-publish.yml line 141 — failing tests report green.
Medium — No dependency vulnerability scan in CI; npm install instead of npm ci; mutable base image python:3.12-slim; no permissions declaration; no non-root USER in Dockerfile.

The Bottom Line

The core service is well-structured (tests, CI, lockfile, license all present) but the codebase carries real maintenance debt: import cycles, oversized modules, and a 782-line config file. The claude-hooks layer is the most polished part. Use it if you need self-hosted agent memory without cloud lock-in — but budget time for the refactoring flagged above before scaling it.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

1,147 files

Python473
Markdown321
Shell89
JavaScript50
YAML39
JSON36

ReactDjangoFlaskFastAPIExpressDockerKubernetesLangChainVector store

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["tests 168 modules"] g1["src 152 modules"] g2["scripts 146 modules"] g3["claude-hooks 43 modules"] g4["video 28 modules"] g5["tools 5 modules"] g6["docs 3 modules"] g0 -->|38| g1 g2 -->|21| g1 g2 -->|1| g3

Module dependencies

The 10 most depended-upon modules of 552, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_rc_mcp_memory_service_config["config"] n1_memory_service_models_memory["memory"] n2__memory_service_storage_base["base"] n3_service_web_oauth_middleware["middleware"] n4_y_service_storage_sqlite_vec["sqlite_vec"] n5_ory_service_web_dependencies["dependencies"] n6_memory_service_utils_hashing["hashing"] n7__mcp_memory_service___init__["__init__"] n8_y_service_storage_cloudflare["cloudflare"] n9_y_service_consolidation_base["base"] n0_rc_mcp_memory_service_config --> n7__mcp_memory_service___init__ n9_y_service_consolidation_base --> n1_memory_service_models_memory n2__memory_service_storage_base --> n1_memory_service_models_memory n2__memory_service_storage_base --> n0_rc_mcp_memory_service_config n8_y_service_storage_cloudflare --> n2__memory_service_storage_base n8_y_service_storage_cloudflare --> n1_memory_service_models_memory n8_y_service_storage_cloudflare --> n0_rc_mcp_memory_service_config n4_y_service_storage_sqlite_vec --> n2__memory_service_storage_base n4_y_service_storage_sqlite_vec --> n1_memory_service_models_memory n4_y_service_storage_sqlite_vec --> n0_rc_mcp_memory_service_config n5_ory_service_web_dependencies --> n2__memory_service_storage_base n5_ory_service_web_dependencies --> n0_rc_mcp_memory_service_config n3_service_web_oauth_middleware --> n0_rc_mcp_memory_service_config classDef cyc stroke:#ef4444,stroke-width:2px; class n0_rc_mcp_memory_service_config,n2__memory_service_storage_base,n4_y_service_storage_sqlite_vec,n7__mcp_memory_service___init__,n8_y_service_storage_cloudflare cyc;

Dependencies

11 of 29 declared dependencies are a major version behind. Resolved 29 of 29 against the registry.

Package	Declared	Latest	Behind
`sinon`	^17.0.0	22.1.0	5 major
`cryptography`	>=46.0.6	50.0.0	4 major
`sentence-transformers`	>=2.2.2	5.7.0	3 major
`aiofiles`	>=23.2.1	25.1.0	2 major
`chardet`	>=5.0.0	7.6.0	2 major
`psutil`	>=5.9.0	7.2.2	2 major
`build`	>=0.10.0	1.5.0	1 major
`mcp`	>=1.8.0,<2.0.0	2.0.0	1 major

Open in Code Brain → See its neighbourhood →

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high3

medium6

low1

Pin third-party GitHub Actions to a commit SHAhigh5 occurrences

.github/workflows

docker/setup-buildx-action@v4, docker/login-action@v4, docker/metadata-action@v6, docker/build-push-action@v7

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Remove the committed .env and rotate what it holdshigh

archive/configs/.env.sqlite.backup

A tracked .env is the most common route for a working key to reach a public clone, and it is the file the app actually loads, so the value is usually live.

Fix: git rm --cached the file, add it to .gitignore, rotate every credential it names, commit a .env.example with empty values.

Remove continue-on-error from steps that gate correctnesshigh

.github/workflows/docker-publish.yml

line 141 on a correctness step

A failing test suite reports a green check, which is precisely the path this audit exists to close.

Fix: Delete continue-on-error, or move a genuinely advisory step into a separate non-required job.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/bridge-tests.yml

2 workflow(s) declare no permissions

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Install from the lockfile in CImedium

.github/workflows

npm install with a committed package-lock.json

A fresh resolution in CI means the tested dependency set is not the locked one, so the failure only appears after merge.

Fix: Use npm ci, yarn install --immutable, or pnpm install --frozen-lockfile.

Pin the container base image by digestmedium

tools/docker/Dockerfile

python:3.12-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/bridge-tests.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

tools/docker/Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/bridge-tests.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.

View on GitHub All Projects