cogitlog-mcp

MCP server for cogitlog — gives AI agents direct access to session memory via the Model Context Protocol.

Install

npm install -g cogitlog cogitlog-mcp

Requires cogitlog 0.8.0 or newer. shallow, descriptions, description and relates_to are 0.8.0 flags. cogitlog_context needs at least 0.7.0 — against 0.6.x and older it fails with unknown command 'context', which is worth checking if that tool misbehaves: run cogitlog --version before assuming the server is at fault.

Configure

Add to your MCP settings (e.g. ~/.claude/settings.json for Claude Code):

{
  "mcpServers": {
    "cogitlog": {
      "command": "cogitlog-mcp",
      "env": {
        "COGITLOG_CWD": "/path/to/your/project"
      }
    }
  }
}

COGITLOG_CWD tells the server which project's .cogitlog/ to use. If omitted, it defaults to the server's working directory.

Tools

Reading (query past reasoning)

| Tool | Description | |------|-------------| | cogitlog_why | Show decisions that reference a file | | cogitlog_context | Show all events related to a file (brief for the last 3 sessions) | | cogitlog_query | Search every session — descriptions, bodies, rejected alternatives, tags | | cogitlog_log | List recent sessions (descriptions for one line per event) | | cogitlog_show | Show full details of a session | | cogitlog_status | Show current session status |

Writing (record reasoning)

| Tool | Description | |------|-------------| | cogitlog_begin | Open a new session | | cogitlog_close | Close the current session | | cogitlog_note | Add a note | | cogitlog_decision | Record a decision | | cogitlog_attempt | Record an attempt | | cogitlog_uncertainty | Flag an uncertainty |

Every writing tool accepts description (a one-line summary — what search and listings scan) and relates_to (session ids this event points at).

Changelog

0.3.0

• cogitlog_query: deep replaced by shallow. Deep search is the CLI default as of 0.8.0, so the old flag no longer meant anything; shallow restores the narrow search.
• cogitlog_log: added descriptions.
• All writing tools: added description and relates_to.
• Server instructions rewritten to lead with reading before editing, to give concrete triggers for each event type, and to state that the store is plain JSONL readable without these tools.

How it works

The server wraps the cogitlog CLI — each tool call runs the corresponding cogitlog command and returns the output. The server's instructions field tells the agent to check prior reasoning before modifying files and to open sessions at the start of tasks.

License

MIT