Mem9

Mem9 is an open-source, project-scoped memory service for Codex, Claude, and other MCP-compatible coding agents. It keeps durable project knowledge and CLI session metadata available across tools and conversations without treating memory as a source of current external facts.

Why Mem9

• Resolves projects from the workspace path, Git remote, and branch.
• Stores atomic architecture decisions, conventions, business rules, and TODOs.
• Combines vector and text retrieval with PostgreSQL and pgvector.
• Exposes nine memory and session tools through MCP Streamable HTTP and STDIO.
• Shares one service across Codex, Claude, and compatible CLI clients.
• Includes focused tests and runnable HTTP/MCP smoke checks.

flowchart LR
  A[Codex / Claude / MCP client] -->|MCP| B[Mem9]
  B --> C[Project resolver]
  B --> D[Embedding client]
  C --> E[(PostgreSQL + pgvector)]
  D --> E

Loading

Requirements

• Python 3.11+
• uv
• PostgreSQL with pgvector, such as Supabase Postgres
• An OpenAI API key for vector embeddings; text search remains available when embeddings are not configured

Quick Start

git clone https://github.com/luuhung93/mem9.git
cd mem9
cp .env.example .env
# Add your database credentials and optional OpenAI API key to .env.

set -a
source .env
set +a

psql "$DIRECT_URL" -v ON_ERROR_STOP=1 -f migrations/001_init.sql
uv run --locked --with-editable . memory-service

The HTTP service listens on http://127.0.0.1:8766 by default:

curl -fsS http://127.0.0.1:8766/health

MCP Setup

Mem9 exposes Streamable HTTP at http://127.0.0.1:8766/mcp.

Codex:

codex mcp add memory --url http://127.0.0.1:8766/mcp
codex mcp get memory

Claude:

claude mcp add --transport http --scope user memory \
  http://127.0.0.1:8766/mcp
claude mcp get memory

Restart active CLI sessions after changing MCP configuration.

MCP Tools

Memory tools:

• memory_search
• memory_store
• memory_update
• memory_delete
• memory_projects

Session tools:

• session_register
• session_list
• session_get
• session_delete

Each CLI should call session_register once at startup with the absolute workspace root, client name, external resume/session ID, and a short title. Codex should use CODEX_THREAD_ID as the external session ID.

Example Workflow

Store one durable project fact:

{
  "workspace_root": "/path/to/project",
  "category": "architecture",
  "content": {
    "fact": "The API uses repository classes for database access."
  }
}

Search before starting related work:

{
  "workspace_root": "/path/to/project",
  "query": "database access architecture"
}

Do not store secrets, source code, build logs, transient errors, or complete conversations. Store one durable fact per memory.

Running with PM2

pm2 start ecosystem.config.cjs
pm2 save
pm2 status mem9

The PM2 configuration uses the repository directory as its working directory and reads secrets from .env.

Development

Run the local checks:

set -a
source .env
set +a

uv lock --check
uv run --locked pytest -q
uv run --locked --with-editable . python scripts/self_check.py
uv run --locked python -m compileall -q src scripts tests

With the service running, verify HTTP and MCP transports:

uv run --locked --with-editable . python scripts/http_smoke.py
uv run --locked --with-editable . python scripts/mcp_smoke.py
uv run --locked --with-editable . python scripts/mcp_http_smoke.py

The smoke checks clean up the memory and session records they create.

Architecture

src/memory_service/
  app.py             FastAPI lifecycle and HTTP routes
  database.py        asyncpg pool setup
  embeddings.py      OpenAI embedding client
  project_context.py Git and workspace project resolver
  repositories/      PostgreSQL memory and session persistence
  mcp_tools/          MCP memory and session tool definitions
  mcp_server.py       STDIO and Streamable HTTP MCP adapter
migrations/           ordered PostgreSQL schema migrations
scripts/              runnable self-checks and smoke tests
tests/                repository and project resolver tests

See ai/ARCHITECTURE.md for implementation details.

Security

Please report vulnerabilities privately as described in SECURITY.md. Never include credentials, private project data, or production database contents in a public issue.

License

Mem9 is licensed under the MIT License.