MCP

Give any MCP-speaking assistant a memory — a local repository on your machine, or a hosted namespace over the API.

Every GitLoom operation is exposed to an assistant over the Model Context Protocol, generated from the same definitions the CLI dispatches through — the two front-ends cannot drift apart, because they are the same code.

There are two servers, for two different deployments of memory:

	backs onto	needs	when to use it
`gitloom mcp`	a git repository on this machine	the CLI, which is free	memory lives with you, works offline
`@gitloomhq/mcp`	a namespace in your GitLoom account	an API key, `npx`	memory is hosted, shared across your machines and your app

The local server

gitloom mcp --repo ~/memory

Speaks JSON-RPC over stdio, which is what every editor launches — this is the mode --http exists to opt out of, not the exception. Run from a terminal it looks frozen: that is correct, a terminal is not an MCP client.

gitloom mcp --read-only                              # search and recall, no writes
gitloom mcp --http 127.0.0.1:7000 --token "$(openssl rand -hex 16)"

Requires the [CLI](/docs/cli.html#install), which is free. A local memory is not a hosted account, so it needs no API key.

The hosted server

GITLOOM_API_KEY=gl_live_... npx -y @gitloomhq/mcp   # current: 0.3.0

No install step beyond npx fetching it, and no local repository — every call reaches your GitLoom account over HTTPS. Three tools: recall_memory, save_memory and find_skill. Their descriptions and schemas come from @gitloomhq/sdk, so a tool call behaves identically whether it arrives through this server, through the SDK directly, or via the OpenAI/Anthropic tool-calling formats.

{
  "mcpServers": {
    "gitloom": {
      "command": "npx",
      "args": ["-y", "@gitloomhq/mcp"],
      "env": { "GITLOOM_API_KEY": "gl_live_..." }
    }
  }
}

Variable	Purpose
`GITLOOM_API_KEY`	required — create one at app.gitloom.cloud
`GITLOOM_NAMESPACE`	which namespace to use (default: the account's default)
`GITLOOM_BASE_URL`	override the API host

What each tool takes:

tool	arguments
`recall_memory`	`query`; optional `tags` (any of them), `since`, `until`, `time_field`, `tiers`, `paths`
`save_memory`	`fact`; optional `tags`, `occurred_at`
`find_skill`	`task`

since, until and occurred_at take a date (YYYY-MM-DD) or an RFC 3339 time. time_field picks the time since and until bound: occurred, when the thing happened, which is the default here; or created or updated, when the memory was written or last changed. With filters and no query, recall_memory lists every memory they match, newest first:

{"name": "recall_memory", "arguments": {"tags": ["trip"], "since": "2026-05-01", "until": "2026-05-31"}}

Each memory it returns starts with the day it happened, when that is known, so the model reads when something happened, not when it was stored:

- [2026-05-14] Flew to Tokyo from Bengaluru.

Connecting an editor

For Claude Code on the free plan, without the CLI, see Claude Code — one claude mcp add line.

gitloom install writes the configuration in each host's own shape, so there is no plugin to install for any of them — they already speak MCP, and this just points them at a server.

gitloom install claude-code             # print it
gitloom install codex --write           # write it into place
gitloom install opencode --project      # scope it to this project
gitloom install claude-code --cloud --write   # point at the hosted server instead

Supported hosts: claude-code, openclaw, opencode, codex, hermes. Add --cloud to any of them to install @gitloomhq/mcp (needs GITLOOM_API_KEY) instead of the local gitloom mcp (needs --repo).

Claude Desktop, by hand, in claude_desktop_config.json:

{
  "mcpServers": {
    "gitloom": {
      "command": "gitloom",
      "args": ["mcp", "--repo", "/absolute/path/to/memory"]
    }
  }
}

What a client sees

Every toolkit operation appears as a tool: remember, recall, search, semantic_search, related, tree, topics, list_vocab, embed_pending, and more. Two of them, ingest and answer, are model-driven and only appear when a model is configured via GITLOOM_MODEL and a provider key — a client listing tools sees exactly what will work, not operations that fail on every call because nothing answers them.

remember takes tags, occurred_at and tz. search and semantic_search take tags (every one must match), since, until, time_field and tz. search with a filter and no query doesn't rank: it lists every memory the filters match, newest first by time_field. The CLI page explains the times and their formats.

{"name": "search", "arguments": {"tags": ["trip"], "time_field": "occurred", "since": "2026-05-01"}}

Both servers describe every parameter the same way a person reading gitloom --help would see it, because the schema and the CLI flag come from one op definition in toolkit. Nothing here is a second copy that can quietly fall out of sync with the first.