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.

cogmem verify              # check all memories and the log head
cogmem receipt <memory-id> # prove a memory is in the signed log
cogmem revoke <memory-id>  # revoke a memory (Bitstring Status List)
cogmem status-list         # emit the signed revocation status-list credential

# examples/c2pa-agent-credential/ is a real signed C2PA manifest
# whose agent identity validates in c2patool
./examples/c2pa-agent-credential/verify.sh

Standards alignment

cogmem is built on published standards, and it is precise about where it conforms versus where it is -style (compatible in shape and crypto, short of full profile conformance). The primitives are real Ed25519 signatures over real canonical byte structures — nothing here is mocked.

Toward full SCITT conformance. Three bounded steps, no new cryptography: (1) move iss/sub/content-type from the statement payload into the COSE protected header as CWT_Claims; (2) emit inclusion proofs as COSE Receipts (draft-ietf-cose-merkle-tree-proofs) in the statement's unprotected header; (3) make the external witness a mandatory Transparency-Service role distinct from the issuing agent. Steps 1–2 are re-encoding; step 3 is the architectural one, since a single-party log is a compatible format rather than meaningful transparency.

Privacy

cogmem is local-first by design. Memories, embeddings, and the identity key live on your machine, and semantic recall is fully local — the embedding and reranker models (fastembed) run on-device, so querying your memory never leaves the machine.

The learning pipeline is not local: acquisition, consolidation, the feedback judge, and the project/user-model synthesis send the relevant session transcript to the Anthropic API (ANTHROPIC_API_KEY). That is how rules are extracted and scored. If you need fully-offline operation, run with --no-hooks (recall still works) until a local-model extraction path lands. In short: recall is local; learning calls the API.

Part of the Agent-Provenance Stack

cogmem is one component of the WritersLogic verifiable agent-provenance pipeline — agent identity, memory, reasoning, and signed output, cryptographically bound end to end.

All four share one substrate — COSE_Sign1 / SCITT signed statements (Ed25519) and W3C DID identity — specified in UNIFIED-PROVENANCE.md.

Security

Found a vulnerability? Please report it privately — see SECURITY.md.

License

Apache-2.0 — see LICENSE.