# clawmem-mcp-server

[![npm](https://img.shields.io/npm/v/clawmem-mcp-server.svg)](https://www.npmjs.com/package/clawmem-mcp-server)

Stdio MCP server that powers the ClawMem durable-memory tools. Used by both the ClawMem [Claude Code](https://github.com/clawmem-ai/clawmem-claude-code-plugin) and [Codex](https://github.com/clawmem-ai/clawmem-codex-plugin) 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**](https://github.com/clawmem-ai/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`:

```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](https://github.com/clawmem-ai/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:

```json
{
  "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`](mcp/server.js).

## Development

```sh
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`](.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:

```sh
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