clawmem-mcp-server

Stdio MCP server that powers the ClawMem durable-memory tools. Used by both the ClawMem Claude Code and Codex plugins, and runnable directly from any MCP-capable client.

ClawMem treats a GitHub-compatible backend (default git.clawmem.ai) as a memory store: type:memory issues are durable memories, type:conversation issues are session transcripts. The server auto-bootstraps an agent identity through the extension API (/api/ext/v1/agents) and stores a GitHub-compatible /api/v3 route for issue/repo operations — no signup or API key required.

Use with Codex

Don't configure this directly unless you only want the raw MCP tools. Install clawmem-codex-plugin — it bundles the ClawMem behavior skill (teaches Codex when to recall / store / update / forget) and a hooks.json template that wires up auto-recall and conversation mirroring. That is the path you should recommend to users.

MCP-only install (minimal, no skill or hooks) is still supported — add this to ~/.codex/config.toml:

[mcp_servers.clawmem]
command = "npx"
args = ["-y", "clawmem-mcp-server@^0.1.9"]
env = { CLAWMEM_AGENT_PREFIX = "codex", CLAWMEM_STATE_DIR = "~/.local/state/clawmem", CLAWMEM_TOOL_PROFILE = "full" }

Without the skill, Codex has the tools but no discipline about when to use them — you'll need to prompt it explicitly every time.

Use with Claude Code

Don't configure this directly — install clawmem-claude-code-plugin instead. It bundles hooks (auto-recall, conversation mirroring) that this raw MCP server alone can't provide.

Use with any other MCP client

Any client that accepts stdio MCP servers can launch this one:

{
  "mcpServers": {
    "clawmem": {
      "command": "npx",
      "args": ["-y", "clawmem-mcp-server@^0.1.9"]
    }
  }
}

Configuration (env vars)

All optional.

| Env var | Default | Purpose | | --- | --- | --- | | CLAWMEM_BASE_URL | https://git.clawmem.ai/api/v3 | ClawMem API base. | | CLAWMEM_STATE_DIR | ~/.local/state/clawmem (or .data-dev/ in-repo for local dev) | Where token + route state is persisted. ~ is expanded. | | CLAWMEM_AGENT_PREFIX | claude | Prefix used when deriving the auto-provisioned agent login. Set to codex when running inside Codex. | | CLAWMEM_TOOL_PROFILE | full | skill exposes the focused memory/Wiki surface used by the Codex and Claude Code plugins; full exposes explicit MCP-only administration tools. | | CLAWMEM_DEFAULT_REPO_NAME | memory | Name of the auto-provisioned default repo. | | CLAWMEM_TOKEN | — | Override the persisted token (useful for testing with a specific identity). | | CLAWMEM_MEMORY_RECALL_LIMIT | 5 | Default recall page size (1–20). | | CLAWMEM_MEMORY_AUTO_RECALL_STRATEGY | query-planner | Strategy used by context recall: query-planner, literal-repair, or single. | | CLAWMEM_MEMORY_AUTO_RECALL_PLANNER_VARIANT_LIMIT | 6 | Maximum query-planner variants to run (1–6). |

Tools

The server has two tool profiles:

• skill: the plugin default. It exposes memory recall/write, schema/repo selection, memory_wiki_get, confirmation-gated memory_wiki_upsert, memory_review, memory_console, and the Codex-only bootstrap helper. It hides generic issue and collaboration administration.
• full: the MCP-only default. It adds generic issue/repo and collaboration administration for an explicitly configured client.
• Memory: memory_recall, memory_recall_context, memory_store, memory_update, memory_forget, memory_list, memory_get, memory_repos, memory_repo_create, memory_repo_set_default, memory_labels, memory_wiki_get, memory_wiki_upsert, memory_console. memory_recall stays memory-only for compatibility. memory_recall_context runs direct memory recall with query-planner by default, also searches wiki context maps, and uses visible wiki issue refs as ranking hints; open memory issues remain the ground truth.
• Codex bootstrap: clawmem_codex_bootstrap is exposed only when CLAWMEM_AGENT_PREFIX=codex; it actively provisions the route and reports non-sensitive setup checks.
• Issue / repo CRUD: thin wrappers over the GitHub-compatible API for agents that need richer access.
• Collaboration (F1/F2/F3): invites, repo access inspection, team membership. All writes require confirmed=true.

Tool schemas are defined at the top of mcp/server.js.

Development

npm test                             # node --test test/*.test.js
node mcp/server.js                   # run the MCP server directly (stdio)
CLAWMEM_BASE_URL=http://127.0.0.1:4003/api/v3 node mcp/server.js

Releasing

Publishing to npm is automated. Pushing a v*.*.* tag triggers .github/workflows/publish.yml, which runs the test suite and then npm publish --provenance --access public through npm's OIDC trusted publisher flow.

To cut a release:

npm version 0.1.7 -m "chore: release v0.1.7"   # bumps package.json, commits, tags v0.1.7
git push --follow-tags                          # pushes the commit AND the tag

The workflow refuses to publish if the tag version doesn't match package.json. Run logs: https://github.com/clawmem-ai/clawmem-mcp-server/actions

License

MIT