subcog

Subcog runs as an MCP server that exposes a suite of memory-focused tools for interacting with a persistent memory store used by AI coding assistants. When started, the subcog MCP server listens for requests from MCP clients (such as Claude Desktop or other agents) and exposes a set of consolidated tools for capturing, recalling, and managing memory around code decisions, learnings, and context. Core capabilities include memory capture, semantic search over memories, and a variety of maintenance and knowledge-graph oriented operations. The server can operate via the stdio transport for local development or be exposed over HTTP if you enable the HTTP transport, depending on how you deploy it. Tools are invoked by their MCP names (e.g., subcog_capture, subcog_recall) and are designed to be called as part of an agent’s tool invocation workflow rather than as shell commands, unless you explicitly request a shell/run-in-terminal mode.

To use the MCP server locally, ensure the subcog binary is installed and in your PATH, then run the server (subcog serve). Your Claude Desktop or MCP client will reference the server via the configuration file (claude_desktop_config.json) under mcpServers. The README also documents a fallback using npx if the binary isn’t installed, though in typical deployments you’ll run the binary directly. The available tools cover core memory CRUD and search, lifecycle maintenance, graph queries, prompt/template management, and session information, enabling integrated workflows for capturing decisions, querying memories semantically, and maintaining the memory store over time.

If you enable HTTP transport, you can deploy the server in networked environments and protect access with JWT authentication, making it suitable for production deployments where clients outside your host need to connect.

Prerequisites:

• Rust toolchain (Cargo) installed, or an alternative installation method described below
• Git (optional, for cloning the repository)

Install methods (choose one):

1. Cargo (recommended for Rust developers)

cargo install subcog

2. Homebrew (macOS/Linux)

brew install zircote/tap/subcog

3. Docker (portable deployment)

docker run --rm ghcr.io/zircote/subcog --help

4. Binary download (prebuilt releases)

curl -LO https://github.com/zircote/subcog/releases/latest/download/subcog-VERSION-TARGET.tar.gz
# extract and run the binary from the archive

5. npx fallback (when binary install isn't available)

npx @zircote/subcog --help

Once installed, start the MCP server:

subcog serve

Configuration note:

• If you’re using Claude Desktop or another MCP client, update your mcpServers configuration to point at the subcog binary with the serve command as shown in the README example.

Tips and common issues:

• Ensure the subcog binary is in your PATH when using the standard config. If not, provide an absolute path to the binary in the command field.
• The MCP tool names (e.g., subcog_capture, subcog_recall) are the intended interface for agent-based usage. Do not shell-out to these commands unless you explicitly enable shell mode.
• By default, the stdio transport is used for local development. If you need remote access, enable the HTTP transport with subcog serve --http and consider adding --port and --jwt-secret for production deployments.
• If you install via cargo, you’ll receive automatic updates when you run cargo install --upgrade subcog. For production environments, pin to a specific release tag or image to avoid unexpected changes.
• The MCP server exposes a suite of tools spanning Core, Lifecycle, CRUD, Bulk, Graph, Prompts, Templates, Session, and Compliance. Familiarize yourself with ADR-0061 for the consolidated tool design and avoid invoking tools by shell unless your workflow explicitly requires it.