Agents

MCP server

Both transports, the five tools with parameters and examples, and space conventions.

greatmemory speaks the Model Context Protocol, so any MCP-capable agent gets persistent long-term memory as a set of thirteen tools. The MCP server is the same binary and the same engine as the HTTP API - no separate install.

Transports

stdio (recommended for local agents)

gmem mcp

Runs the MCP server on stdin/stdout. This mode does not need gmem serve running: it opens the database directly from the configured data dir (GM_DATA_DIR, default ./.greatmemory). Logs go to stderr so stdout stays clean for MCP framing.

Flags: --config <path> (alternate greatmemory.toml) and --data-dir <path>. Because agents may launch the process from any working directory, prefer an absolute GM_DATA_DIR (or --data-dir) so every client sees the same memories.

Streamable HTTP

A running gmem serve also exposes MCP at POST /mcp (http://127.0.0.1:7437/mcp), in stateless JSON mode, behind the same bearer auth as /v1 when GM_API_KEYS is set. Use this when you want several clients sharing one live instance.

In v0.1 the HTTP transport keeps its loopback Host validation (DNS-rebinding protection), so remote /mcp deployments are out of scope - use stdio, or a local HTTP connection.

The thirteen tools

All tools default space to "default". Spaces let different projects, users, or agents keep separate memories.

remember

Store a piece of information in long-term memory. Returns the new memory's id.

{"name": "remember", "arguments": {"content": "Deploys go through the release branch.", "space": "myproject"}}

Returns:

{"id": "0196a7c2-...", "space": "myproject"}

recall

Search long-term memory; returns the most relevant chunks and known facts as JSON.

{"name": "recall", "arguments": {"query": "how do we deploy?", "space": "myproject", "k": 5}}

Returns:

{
  "chunks": [{"chunk_id": "...", "doc_id": "...", "text": "Deploys go through the release branch.", "score": 0.021}],
  "facts": []
}

get_context

Build a ready-to-use context block for a query: known facts first, then relevant memories, within a token budget. Returns plain text, not JSON - made to be pasted straight into a prompt. Usually the best single call before answering.

{"name": "get_context", "arguments": {"query": "deployment process", "max_tokens": 1000}}

get_profile

Summarize everything known in a space: active facts grouped by predicate, as JSON. Call it once at session start for standing context.

Returns:

{"facts": {"deploy_branch": [{"subject": "myproject", "object": "release", "confidence": 0.9, "fact_id": "..."}]}}

timeline

Trace how facts about an entity changed over time. Returns the full bi-temporal history for a subject - every recorded fact, oldest first, with its validity interval, including superseded values. Answers "what did I know about X, and when?".

{"name": "timeline", "arguments": {"subject": "user", "predicate": "lives_in"}}

Returns:

{
  "edges": [
    {"subject": "user", "predicate": "lives_in", "object": "London", "valid_from": "2020-01-01T00:00:00Z", "valid_until": "2026-01-01T00:00:00Z", "is_current": true, "superseded_by": "..."},
    {"subject": "user", "predicate": "lives_in", "object": "Dubai", "valid_from": "2026-01-01T00:00:00Z", "valid_until": null, "is_current": true, "superseded_by": null}
  ]
}

Episodes

Episodic memory: group related events under a named episode (a project, an incident, a meeting) and reconstruct them later.

• create_episode - name (required), space, summary. Returns {"id", "name", "space"}.
• add_episode_event - episode_id (required), kind (required), ref_id (a related memory id), note. Returns {"ok": true}.
• get_episode - episode_id. Returns {"episode": {...}, "events": [...]} in time order - the reconstruction.
• list_episodes - space. Returns {"episodes": [...]}, newest first.

{"name": "create_episode", "arguments": {"name": "Project Athena", "space": "work"}}
{"name": "add_episode_event", "arguments": {"episode_id": "0196...", "kind": "decision", "note": "Chose Postgres"}}
{"name": "get_episode", "arguments": {"episode_id": "0196..."}}

Memory cards (A-MEM)

Atomic, linked notes - an agent writes what's worth remembering and greatmemory auto-links related cards into a navigable web.

• create_card - title (required), summary (required), space, keywords, tags. Auto-links to cards sharing keywords/tags. Returns {"id"}.
• get_card - card_id. Returns {"card": {...}, "links": [...]} (related cards, strongest first).
• list_cards - space. Returns {"cards": [...]}, newest first.

{"name": "create_card", "arguments": {"title": "Postgres tuning", "summary": "Bump shared_buffers to 25% RAM", "keywords": ["postgres"], "tags": ["db"]}}
{"name": "get_card", "arguments": {"card_id": "0196..."}}

forget

Delete a memory by id. Facts already extracted from it are kept but lose their link to it.

Returns:

{"deleted": "<id>"}

Space conventions

• space is a plain namespace string. Use one space per project (local multi-project use) or one space per user (multi-user servers) so memories don't bleed across contexts.
• A sensible rhythm for an agent: get_profile once at session start, get_context per question, remember whenever something durable is learned, forget only on explicit request.
• Don't store transient chit-chat - greatmemory's fact extractor also ignores it.

Client setup guides

• Claude Code
• Codex CLI
• Hermes
• OpenClaw
• Custom agents over REST