Skip to main content

​
MCP Integration

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

​
Available tools

ToolDescription
remem_queryRaw POST /v1/query response (supports mode, max_results, synthesize, filters, include_facts, entity, facts_only_latest, namespaces)
remem_searchFast formatted search output (namespaces supported)
remem_summarizeRich synthesized answer with sources (namespaces supported)
remem_memory_queryQuery the knowledge graph for facts about entities
remem_list_entitiesList memory entities (people, orgs, projects, etc.)
remem_get_entity_factsGet facts for a specific entity by ID
remem_extract_factsTrigger fact extraction for a document (namespace supported)
remem_get_documentGET /v1/documents/{document_id}
remem_get_document_chunksGET /v1/documents/{document_id}/chunks
remem_ingestPOST /v1/documents/ingest for text content (namespace supported)

​
Required environment variables

VariableRequiredDescription
REMEM_API_URLYesAPI base URL (for hosted: https://api.remem.io)
REMEM_API_KEYYesRemem API key (vlt_...)
REMEM_DEFAULT_MODENoDefault query mode (fast or rich)
REMEM_MAX_RESULTSNoDefault max results (1-100)
REMEM_DEFAULT_NAMESPACENoDefault namespace key for write tools when namespace is omitted

​
Claude configuration

{
  "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: 
[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: 
{
  "query": "latest project updates",
  "mode": "rich",
  "namespaces": ["work", "shared"]
}
Write tools accept namespace: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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.