cogmem
A self-improving, verifiable memory layer for AI coding agents.
[](https://github.com/dcondrey/cogmem/actions/workflows/publish.yml) [](https://github.com/dcondrey/cogmem/actions/workflows/codeql.yml) [](https://securityscorecards.dev/viewer/?uri=github.com/dcondrey/cogmem) [](https://www.bestpractices.dev/projects/14401) [](https://github.com/dcondrey/cogmem/blob/main/LICENSE) [](https://github.com/dcondrey/cogmem/blob/main/CODE_OF_CONDUCT.md) [](https://github.com/sponsors/dcondrey)
**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](https://github.com/writerslogic) — local-first recall; your memory and identity key stay on your machine (see [Privacy](#privacy)).
## Installation
### From PyPI
```bash
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:
```bash
git clone https://github.com/writerslogic/cogmem.git
cd cogmem
./install.sh
```
Or in one line:
```bash
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`:
```bash
COGMEM_HOME=/opt/cogmem ./install.sh
```
Or with the one-liner:
```bash
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:
```bash
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:
| Path | Purpose |
|------|---------|
| `$COGMEM_HOME/vault/identity/agent.key` | Ed25519 private key (agent identity, `did:key`) |
| `$COGMEM_HOME/vault/credentials/` | W3C Verifiable Credential storage |
| `$COGMEM_HOME/vault/rules/` | Layer-A (always-load) and Layer-B (recall) rules |
| `$COGMEM_HOME/vault/provenance/log.jsonl` | Append-only hash-chained transparency log |
| `$COGMEM_HOME/vault/provenance/statements/` | COSE_Sign1 SCITT signed statements |
| `$COGMEM_HOME/engine/.venv/` | Python virtualenv with dependencies |
| `$COGMEM_HOME/hooks/` | Claude Code hook scripts |
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:
```json
{
"mcpServers": {
"cogmem": { "command": "cogmem", "args": ["mcp"] }
}
}
```
If the CLI is not on your PATH, use the full path:
```json
{
"mcpServers": {
"cogmem": { "command": "/opt/cogmem/cogmem", "args": ["mcp"] }
}
}
```
Or prefix with `COGMEM_HOME` in a shell wrapper:
```json
{
"mcpServers": {
"cogmem": { "command": "env", "args": ["COGMEM_HOME=/opt/cogmem", "cogmem", "mcp"] }
}
}
```
## Quick Start
```bash
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 # inclusion proof that a memory is committed in the signed log
cogmem statement # 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:
```json
{
"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:
| Event | Hook | What it does |
|---|---|---|
| `SessionStart` | `cogmem-activate.sh` | injects promoted always-load (Layer-A) rules + the self-check |
| `UserPromptSubmit` | `cogmem-recall.sh` | semantic Layer-B recall for the current prompt |
| `PreToolUse(Bash)` | `cogmem-guard.sh` | intercepts known mistakes at the tool-call boundary before they happen |
| `PostToolUse(Edit\|Write)` | `cogmem-context.sh` | tracks which files the session is actively editing |
| `Stop` | `cogmem-capture.sh` | captures the session into memory (acquisition + consolidation) |
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.
Why cogmem? -- learns from outcomes, models failure modes, verifiable memory
Chat-memory systems (Mem0, Letta, Zep) store and retrieve facts. cogmem is built for coding agents and goes further on three axes:
**It learns from outcomes.** A feedback loop scores whether a recalled lesson actually helped, refines rules that prove wrong, and retires ones that mislead.
**It models its own failure modes.** cogmem tracks where the agent tends to go wrong in your work and intercepts known mistakes at the tool-call boundary — before they happen, not afterward.
**Its memory is verifiable.** Each memory is a W3C Verifiable Credential signed by the agent's `did:key`, recorded in a tamper-evident, SCITT-style transparency log. Agent memory is an attack surface; cogmem makes it auditable and poison-resistant.
Features -- two-layer memory, outcome feedback, self-model, project state, cross-project narrative, self-regulation, verifiable credentials
- **Two-layer memory**: always-loaded directives (scope-gated, human-approved) plus a semantic recall tail (local cross-encoder reranking, no data leaves the machine).
- **Outcome feedback and self-refinement**: memories earn or lose trust based on whether they actually helped; contradicted rules are corrected through a safe pipeline.
- **Self-model and guard**: a model of the agent's recurring mistakes, compiled into tripwires that intercept them at the `PreToolUse` boundary.
- **Project-state model**: a living per-project state (goal, claims, open questions, blockers) that gives situational continuity and reasons across time.
- **Cross-project progress narrative**: momentum, stalls, and dependencies across projects, surfaced as alerts.
- **Self-regulation**: recall thresholds tuned automatically against an eval harness.
- **Verifiable Agent Memory**: `did:key` identity, W3C VC-signed memories, COSE_Sign1 SCITT signed statements (byte-compatible with HMS), a hash-chained transparency log with signed Merkle tree head and RFC 6962 inclusion receipts, optional poison-resistance enforcement. See [PROVENANCE.md](./PROVENANCE.md).
Verifiable Memory -- did:key identity, W3C VC, COSE/SCITT, hash-chained log, poison-resistance
cogmem treats every stored memory as a signed artifact:
- **`did:key` identity**: each agent gets a persistent Ed25519 identity, exposed as a W3C DID.
- **W3C Verifiable Credentials**: every memory is signed with `eddsa-jcs-2022` Data Integrity proofs.
- **COSE_Sign1 / SCITT signed statements**: byte-identical to the envelope format used by holographic-memory and crosstalk — independently verifiable by any of the three implementations.
- **Hash-chained transparency log**: append-only JSONL with SHA-256 chaining, a signed Merkle tree head, and RFC 6962-style inclusion receipts.
- **Revocation**: every credential carries a W3C [Bitstring Status List](https://www.w3.org/TR/vc-bitstring-status-list/) entry; a demoted or retired memory is revoked in a signed status-list credential.
- **Poison-resistance**: altered or injected memories fail verification and are rejected before influencing the agent.
```bash
cogmem verify # check all memories and the log head
cogmem receipt # prove a memory is in the signed log
cogmem revoke # revoke a memory (Bitstring Status List)
cogmem status-list # emit the signed revocation status-list credential
```
See [PROVENANCE.md](./PROVENANCE.md) for the full specification.
**Verify the C2PA sample yourself:**
```bash
# examples/c2pa-agent-credential/ is a real signed C2PA manifest
# whose agent identity validates in c2patool
./examples/c2pa-agent-credential/verify.sh
```
This proves the whole chain: agent identity (`cawg.ica.credential_valid`) bound to real cognition — a signed cogmem memory and a signed crosstalk reasoning audit, each an independently verifiable Ed25519 COSE/SCITT statement.
## 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.
| Standard | What cogmem implements | Status |
|---|---|---|
| [W3C DID](https://www.w3.org/TR/did-core/) | `did:key` (Ed25519), `did:web` (publishes an OKP `publicKeyJwk`), `did:jwk` — all with working resolvers | Conformant |
| [W3C VC Data Model 2.0](https://www.w3.org/TR/vc-data-model-2.0/) | VC v2 context, credential `id`, `validFrom`/`validUntil`, `AgentMemoryCredential` / `AIAgentCredential` / `IdentityClaimsAggregationCredential` | Conformant; Verifiable Presentations are roadmap |
| [W3C Data Integrity — `eddsa-jcs-2022`](https://www.w3.org/TR/vc-di-eddsa/) | Ed25519 Data Integrity proof over [RFC 8785](https://www.rfc-editor.org/rfc/rfc8785) JCS canonical bytes (UTF-16 key ordering, literal-UTF-8 strings) | Conformant |
| [W3C Bitstring Status List](https://www.w3.org/TR/vc-bitstring-status-list/) | Every memory carries a `BitstringStatusListEntry`; a demoted/retired memory is revoked (GZIP + multibase `encodedList`) and published in a signed `BitstringStatusListCredential` | Conformant |
| [IETF COSE (RFC 9052)](https://www.rfc-editor.org/rfc/rfc9052) | Untagged and tag-18 `COSE_Sign1`, EdDSA (`-8`) | Conformant; byte-interoperable with the `coset`-based verifiers in the sibling projects |
| [IETF SCITT](https://datatracker.ietf.org/wg/scitt/about/) | `COSE_Sign1` signed statements + an append-only, hash-chained, signed log | SCITT-*style*. Conformant Signed-Statement headers (CWT_Claims), COSE Receipts, and a Transparency Service distinct from the issuer are roadmap — see below |
| [RFC 6962](https://www.rfc-editor.org/rfc/rfc6962) Merkle | Signed tree head, inclusion proofs, verification | Conformant proof math; a witness co-signs the tree head for independent transparency |
| [CAWG Identity Assertion (ICA)](https://cawg.io/identity/) | `IdentityClaimsAggregationCredential` in a tag-18 `COSE_Sign1` over `application/vc`, cross-checked against the C2PA `SignerPayload` | Interoperable with the ICA verifier in `c2pa-rs` |
**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.
| Project | Role |
|---|---|
| **cogmem (this repo)** | Agent identity (CAWG credential) + verifiable, tamper-evident memory (COSE/SCITT) |
| [crosstalk](https://github.com/writerslogic/crosstalk) | Multi-model orchestrator; signs each turn's reasoning/orchestration audit |
| [holographic-memory](https://github.com/writerslogic/holographic-memory) | Durable holographic memory store; cross-verifies signed statements and agent identity |
| WritersProof | C2PA producer: binds identity + memory + reasoning to the signed asset |
All four share one substrate — COSE_Sign1 / SCITT signed statements (Ed25519) and W3C DID identity — specified in [UNIFIED-PROVENANCE.md](./UNIFIED-PROVENANCE.md).
## Security
Found a vulnerability? Please report it privately — see [SECURITY.md](./SECURITY.md).
## License
Apache-2.0 — see [LICENSE](./LICENSE).