# 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.

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

## Requirements

- Python 3.11+
- [uv](https://docs.astral.sh/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

```bash
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:

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

## MCP Setup

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

Codex:

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

Claude:

```bash
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:

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

Search before starting related work:

```json
{
  "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

```bash
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:

```bash
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:

```bash
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

```text
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`](ai/ARCHITECTURE.md) for implementation details.

## Security

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

## License

Mem9 is licensed under the [MIT License](LICENSE).