> ## Documentation Index
> Fetch the complete documentation index at: https://docs.remem.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Integration

> Connect Remem MCP tools to Claude, Codex, and other MCP-compatible clients.

# MCP Integration

Remem ships an MCP server package (`remem-mcp`) that proxies MCP tool calls to your Remem API.

## Available tools

| Tool                        | Description                                                                                                                                           |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `remem_query`               | Raw `POST /v1/query` response (supports `mode`, `max_results`, `synthesize`, `filters`, `include_facts`, `entity`, `facts_only_latest`, `namespaces`) |
| `remem_search`              | Fast formatted search output (`namespaces` supported)                                                                                                 |
| `remem_summarize`           | Rich synthesized answer with sources (`namespaces` supported)                                                                                         |
| `remem_memory_query`        | Query the knowledge graph for facts about entities                                                                                                    |
| `remem_list_entities`       | List memory entities (people, orgs, projects, etc.)                                                                                                   |
| `remem_get_entity_facts`    | Get facts for a specific entity by ID                                                                                                                 |
| `remem_extract_facts`       | Trigger fact extraction for a document (`namespace` supported)                                                                                        |
| `remem_get_document`        | `GET /v1/documents/{document_id}`                                                                                                                     |
| `remem_get_document_chunks` | `GET /v1/documents/{document_id}/chunks`                                                                                                              |
| `remem_ingest`              | `POST /v1/documents/ingest` for text content (`namespace` supported)                                                                                  |

## Required environment variables

| Variable                  | Required | Description                                                       |
| ------------------------- | -------- | ----------------------------------------------------------------- |
| `REMEM_API_URL`           | Yes      | API base URL (for hosted: `https://api.remem.io`)                 |
| `REMEM_API_KEY`           | Yes      | Remem API key (`vlt_...`)                                         |
| `REMEM_DEFAULT_MODE`      | No       | Default query mode (`fast` or `rich`)                             |
| `REMEM_MAX_RESULTS`       | No       | Default max results (1-100)                                       |
| `REMEM_DEFAULT_NAMESPACE` | No       | Default namespace key for write tools when `namespace` is omitted |

## Claude configuration

```json theme={null}
{
  "mcpServers": {
    "remem": {
      "command": "uvx",
      "args": [
        "-q",
        "--from",
        "git+https://github.com/asimgilani/remem.git@master#subdirectory=packages/remem-mcp",
        "remem-mcp"
      ],
      "env": {
        "REMEM_API_URL": "https://api.remem.io",
        "REMEM_API_KEY": "vlt_your_key_here",
        "REMEM_DEFAULT_NAMESPACE": "work"
      }
    }
  }
}
```

## Codex MCP configuration

Add this block in `~/.codex/config.toml`:

```toml theme={null}
[mcp_servers.remem]
command = "uvx"
args = ["-q", "--from", "git+https://github.com/asimgilani/remem.git@master#subdirectory=packages/remem-mcp", "remem-mcp"]

[mcp_servers.remem.env]
REMEM_API_URL = "https://api.remem.io"
REMEM_API_KEY = "vlt_your_key_here"
REMEM_DEFAULT_NAMESPACE = "work"
```

## Namespace-aware tool arguments

Read tools accept `namespaces`:

```json theme={null}
{
  "query": "latest project updates",
  "mode": "rich",
  "namespaces": ["work", "shared"]
}
```

Write tools accept `namespace`:

```json theme={null}
{
  "title": "Research checkpoint",
  "content": "Tried reranker v3 today.",
  "namespace": "research"
}
```

If a write tool omits `namespace`, the packaged MCP server falls back to `REMEM_DEFAULT_NAMESPACE`. If that env var is also unset, the Remem API falls back to the API key's default namespace.

## Query filters for session recall

`remem_query` forwards `filters` exactly as API payload.

Example:

```json theme={null}
{
  "query": "What decisions did we make last session?",
  "mode": "rich",
  "synthesize": true,
  "filters": {
    "checkpoint_project": ["remem"],
    "checkpoint_session": ["2026-02-14-a"],
    "checkpoint_kinds": ["milestone", "final"]
  }
}
```

## Memory Layer tools

The MCP server exposes dedicated tools for the Memory Layer knowledge graph.

### remem\_memory\_query

Query for facts relevant to a topic or entity:

```json theme={null}
{
  "query": "What database does the team use?",
  "entity": "Acme Corp",
  "latest_only": true
}
```

Returns formatted fact lines with type, confidence, and entity associations.

### remem\_list\_entities

Browse entities in the knowledge base:

```json theme={null}
{
  "entity_type": "person",
  "limit": 20
}
```

Returns a formatted list of entities with their fact counts and mention counts.

### remem\_get\_entity\_facts

Get all facts for a specific entity:

```json theme={null}
{
  "entity_id": "uuid-here",
  "latest_only": true,
  "fact_type": "preference"
}
```

### remem\_extract\_facts

Manually trigger fact extraction for a document that has already been ingested:

```json theme={null}
{
  "document_id": "uuid-here"
}
```

## Security notes

* MCP runs locally and uses your API key to call Remem.
* Use lower-scope keys where appropriate (for example `internal` instead of `personal`).
* Never commit `REMEM_API_KEY` values to source control.