cogmem

A self-improving, verifiable memory layer for AI coding agents.

A self-improving, verifiable memory layer for AI coding agents.

cogmem learns how you work across sessions so your agent gets more accurate and more autonomous over time: it stops repeating mistakes, keeps a live model of each project, and surfaces the right lesson at the right moment. Every memory is cryptographically signed and tamper-evident, so a poisoned or altered memory can be detected and rejected before it ever steers the agent.

Developed by WritersLogic — local-first recall; your memory and identity key stay on your machine (see Privacy).

Installation

From PyPI

pip install cogmem            # CLI + MCP server + verifiable-memory tools
pip install 'cogmem[recall]'  # add local semantic recall (fastembed)
cogmem init                   # wire the Claude Code hooks + build the index

pip install cogmem gives you the cogmem CLI and the MCP server (cogmem mcp, or uvx cogmem mcp on demand) — the verifiable-memory tools need only the core install. Add the [recall] extra for local semantic recall, then run cogmem init to wire the full learning loop (the SessionStart/UserPromptSubmit/Stop hooks and the index) into Claude Code. cogmem init is idempotent; re-run it any time.

Clone installer (turnkey, with the warm daemon)

The clone installer does everything pip install + cogmem init does, plus sets up the warm recall daemon (launchd/systemd) as a managed service:

git clone https://github.com/writerslogic/cogmem.git
cd cogmem
./install.sh

Or in one line:

curl -fsSL https://raw.githubusercontent.com/writerslogic/cogmem/main/install.sh | bash

install.sh is idempotent — run it again any time to upgrade in place. It sets up the code under ~/.claude/cogmem, a self-contained virtualenv with dependencies, the cogmem CLI on your PATH, the Claude Code hooks, and a warm recall daemon (a launchd agent on macOS, a systemd --user service on Linux). Requires Python 3.12+; semantic recall runs on a local model (fastembed, no external API). Pass --no-daemon or --no-hooks to skip those steps; set COGMEM_HOME to install elsewhere — the CLI, engine, and hooks all resolve it at runtime, so a non-default install keeps its memory and identity fully self-contained.

Custom Installation

Install to a different directory

Set COGMEM_HOME to place cogmem somewhere other than the default ~/.claude/cogmem:

COGMEM_HOME=/opt/cogmem ./install.sh

Or with the one-liner:

curl -fsSL https://raw.githubusercontent.com/writerslogic/cogmem/main/install.sh | COGMEM_HOME=/opt/cogmem bash

The installer copies the code, creates the virtualenv, and symlinks the CLI to ~/.local/bin/cogmem (or wherever COGMEM_BIN points).

CLI path

Set COGMEM_BIN to control where the cogmem CLI symlink is placed:

COGMEM_BIN=$HOME/.cargo/bin COGMEM_HOME=/opt/cogmem ./install.sh

If COGMEM_BIN is not on your PATH, the installer prints a warning. You can always invoke cogmem directly from $COGMEM_HOME/cogmem.

How data directories and identity keys are resolved

At runtime the CLI and engine read COGMEM_HOME from the environment. When it is unset they fall back to ~/.claude/cogmem. All runtime data lives under the vault/ subdirectory:

The identity key is generated on first run (via cogmem status or any engine operation) and persisted at $COGMEM_HOME/vault/identity/agent.key. The corresponding did:key is derived from the Ed25519 public key. Moving or reinstalling cogmem to a new COGMEM_HOME creates a fresh identity unless you migrate the vault/ directory.

MCP client with a non-default install

The standard MCP client configuration works regardless of COGMEM_HOME because the cogmem CLI resolves the environment variable at runtime:

{
  "mcpServers": {
    "cogmem": { "command": "cogmem", "args": ["mcp"] }
  }
}

If the CLI is not on your PATH, use the full path:

{
  "mcpServers": {
    "cogmem": { "command": "/opt/cogmem/cogmem", "args": ["mcp"] }
  }
}

Or prefix with COGMEM_HOME in a shell wrapper:

{
  "mcpServers": {
    "cogmem": { "command": "env", "args": ["COGMEM_HOME=/opt/cogmem", "cogmem", "mcp"] }
  }
}

Quick Start

cogmem status           # health check, metrics, agent DID
cogmem doctor           # end-to-end learning-loop health (daemon, API key, trust, backlog)
cogmem recall "..."     # surface relevant past lessons for a task
cogmem note "..."       # record a decision or finding mid-task
cogmem verify           # verify every memory's credential + the transparency log
cogmem receipt <id>     # inclusion proof that a memory is committed in the signed log
cogmem statement <id>   # COSE_Sign1 SCITT signed statement (verifiable by HMS too)
cogmem trust            # show the trusted agent identity (warns on a key mismatch)
cogmem trust --rotate   # re-anchor trust after an intentional key change
cogmem review list      # approve always-load rules
cogmem mcp              # run the MCP server (stdio) for any MCP client

MCP Integration

Run cogmem as an MCP server and connect any MCP-compatible client:

{
  "mcpServers": {
    "cogmem": { "command": "cogmem", "args": ["mcp"] }
  }
}

Eight tools are exposed: recall, note, status, verify, receipt, tree_head, progress, review_pending, plus read-only resources (the live user model and per-project state).

Claude Code Integration

install.sh wires cogmem into Claude Code automatically (idempotently merged into ~/.claude/settings.json) — no manual invocation required. Five hooks make the memory loop run in the background:

Every hook is strictly fail-open: any error, timeout, or cold daemon injects nothing and never blocks your prompt. The scripts live in ~/.claude/cogmem/hooks/; re-run install.sh (or ./install.sh --no-daemon) to refresh the wiring.