A self-improving, verifiable memory layer for AI coding agents.
\n\n \n\n[](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)\n\n\n**A self-improving, verifiable memory layer for AI coding agents.**\n\ncogmem 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.\n\n> Developed by [WritersLogic](https://github.com/writerslogic) — local-first recall; your memory and identity key stay on your machine (see [Privacy](#privacy)).\n\n## Installation\n\n### From PyPI\n\n```bash\npip install cogmem # CLI + MCP server + verifiable-memory tools\npip install 'cogmem[recall]' # add local semantic recall (fastembed)\ncogmem init # wire the Claude Code hooks + build the index\n```\n\n`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.\n\n### Clone installer (turnkey, with the warm daemon)\n\nThe clone installer does everything `pip install` + `cogmem init` does, plus sets up the warm recall daemon (launchd/systemd) as a managed service:\n\n```bash\ngit clone https://github.com/writerslogic/cogmem.git\ncd cogmem\n./install.sh\n```\n\nOr in one line:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/writerslogic/cogmem/main/install.sh | bash\n```\n\n`install.sh` is idempotent — run it again any time to upgrade in place. It sets up\nthe code under `~/.claude/cogmem`, a self-contained virtualenv with dependencies,\nthe `cogmem` CLI on your PATH, the Claude Code hooks, and a warm recall daemon\n(a launchd agent on macOS, a `systemd --user` service on Linux). Requires\n**Python 3.12+**; semantic recall runs on a local model (fastembed, no external\nAPI). Pass `--no-daemon` or `--no-hooks` to skip those steps; set `COGMEM_HOME`\nto install elsewhere — the CLI, engine, and hooks all resolve it at runtime, so\na non-default install keeps its memory and identity fully self-contained.\n\n## Custom Installation\n\n### Install to a different directory\n\nSet `COGMEM_HOME` to place cogmem somewhere other than the default\n`~/.claude/cogmem`:\n\n```bash\nCOGMEM_HOME=/opt/cogmem ./install.sh\n```\n\nOr with the one-liner:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/writerslogic/cogmem/main/install.sh | COGMEM_HOME=/opt/cogmem bash\n```\n\nThe installer copies the code, creates the virtualenv, and symlinks the CLI to\n`~/.local/bin/cogmem` (or wherever `COGMEM_BIN` points).\n\n### CLI path\n\nSet `COGMEM_BIN` to control where the `cogmem` CLI symlink is placed:\n\n```bash\nCOGMEM_BIN=$HOME/.cargo/bin COGMEM_HOME=/opt/cogmem ./install.sh\n```\n\nIf `COGMEM_BIN` is not on your PATH, the installer prints a warning. You can\nalways invoke cogmem directly from `$COGMEM_HOME/cogmem`.\n\n### How data directories and identity keys are resolved\n\nAt runtime the CLI and engine read `COGMEM_HOME` from the environment. When it is\nunset they fall back to `~/.claude/cogmem`. All runtime data lives under the\n`vault/` subdirectory:\n\n| Path | Purpose |\n|------|---------|\n| `$COGMEM_HOME/vault/identity/agent.key` | Ed25519 private key (agent identity, `did:key`) |\n| `$COGMEM_HOME/vault/credentials/` | W3C Verifiable Credential storage |\n| `$COGMEM_HOME/vault/rules/` | Layer-A (always-load) and Layer-B (recall) rules |\n| `$COGMEM_HOME/vault/provenance/log.jsonl` | Append-only hash-chained transparency log |\n| `$COGMEM_HOME/vault/provenance/statements/` | COSE_Sign1 SCITT signed statements |\n| `$COGMEM_HOME/engine/.venv/` | Python virtualenv with dependencies |\n| `$COGMEM_HOME/hooks/` | Claude Code hook scripts |\n\nThe identity key is generated on first run (via `cogmem status` or any engine\noperation) and persisted at `$COGMEM_HOME/vault/identity/agent.key`. The\ncorresponding `did:key` is derived from the Ed25519 public key. Moving or\nreinstalling cogmem to a new `COGMEM_HOME` creates a fresh identity unless you\nmigrate the `vault/` directory.\n\n### MCP client with a non-default install\n\nThe standard MCP client configuration works regardless of `COGMEM_HOME` because\nthe `cogmem` CLI resolves the environment variable at runtime:\n\n```json\n{\n \"mcpServers\": {\n \"cogmem\": { \"command\": \"cogmem\", \"args\": [\"mcp\"] }\n }\n}\n```\n\nIf the CLI is not on your PATH, use the full path:\n\n```json\n{\n \"mcpServers\": {\n \"cogmem\": { \"command\": \"/opt/cogmem/cogmem\", \"args\": [\"mcp\"] }\n }\n}\n```\n\nOr prefix with `COGMEM_HOME` in a shell wrapper:\n\n```json\n{\n \"mcpServers\": {\n \"cogmem\": { \"command\": \"env\", \"args\": [\"COGMEM_HOME=/opt/cogmem\", \"cogmem\", \"mcp\"] }\n }\n}\n```\n\n## Quick Start\n\n```bash\ncogmem status # health check, metrics, agent DID\ncogmem doctor # end-to-end learning-loop health (daemon, API key, trust, backlog)\ncogmem recall \"...\" # surface relevant past lessons for a task\ncogmem note \"...\" # record a decision or finding mid-task\ncogmem verify # verify every memory's credential + the transparency log\ncogmem receipt # inclusion proof that a memory is committed in the signed log\ncogmem statement # COSE_Sign1 SCITT signed statement (verifiable by HMS too)\ncogmem trust # show the trusted agent identity (warns on a key mismatch)\ncogmem trust --rotate # re-anchor trust after an intentional key change\ncogmem review list # approve always-load rules\ncogmem mcp # run the MCP server (stdio) for any MCP client\n```\n\n## MCP Integration\n\nRun cogmem as an MCP server and connect any MCP-compatible client:\n\n```json\n{\n \"mcpServers\": {\n \"cogmem\": { \"command\": \"cogmem\", \"args\": [\"mcp\"] }\n }\n}\n```\n\nEight 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).\n\n## Claude Code Integration\n\n`install.sh` wires cogmem into Claude Code automatically (idempotently merged into\n`~/.claude/settings.json`) — no manual invocation required. Five hooks make the\nmemory loop run in the background:\n\n| Event | Hook | What it does |\n|---|---|---|\n| `SessionStart` | `cogmem-activate.sh` | injects promoted always-load (Layer-A) rules + the self-check |\n| `UserPromptSubmit` | `cogmem-recall.sh` | semantic Layer-B recall for the current prompt |\n| `PreToolUse(Bash)` | `cogmem-guard.sh` | intercepts known mistakes at the tool-call boundary before they happen |\n| `PostToolUse(Edit\\|Write)` | `cogmem-context.sh` | tracks which files the session is actively editing |\n| `Stop` | `cogmem-capture.sh` | captures the session into memory (acquisition + consolidation) |\n\nEvery hook is strictly fail-open: any error, timeout, or cold daemon injects\nnothing and never blocks your prompt. The scripts live in `~/.claude/cogmem/hooks/`;\nre-run `install.sh` (or `./install.sh --no-daemon`) to refresh the wiring.\n\n\nWhy cogmem? -- learns from outcomes, models failure modes, verifiable memory\n\nChat-memory systems (Mem0, Letta, Zep) store and retrieve facts. cogmem is built for coding agents and goes further on three axes:\n\n**It learns from outcomes.** A feedback loop scores whether a recalled lesson actually helped, refines rules that prove wrong, and retires ones that mislead.\n\n**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.\n\n**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.\n\n\n\n\nFeatures -- two-layer memory, outcome feedback, self-model, project state, cross-project narrative, self-regulation, verifiable credentials\n\n- **Two-layer memory**: always-loaded directives (scope-gated, human-approved) plus a semantic recall tail (local cross-encoder reranking, no data leaves the machine).\n- **Outcome feedback and self-refinement**: memories earn or lose trust based on whether they actually helped; contradicted rules are corrected through a safe pipeline.\n- **Self-model and guard**: a model of the agent's recurring mistakes, compiled into tripwires that intercept them at the `PreToolUse` boundary.\n- **Project-state model**: a living per-project state (goal, claims, open questions, blockers) that gives situational continuity and reasons across time.\n- **Cross-project progress narrative**: momentum, stalls, and dependencies across projects, surfaced as alerts.\n- **Self-regulation**: recall thresholds tuned automatically against an eval harness.\n- **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).\n\n\n\n\nVerifiable Memory -- did:key identity, W3C VC, COSE/SCITT, hash-chained log, poison-resistance\n\ncogmem treats every stored memory as a signed artifact:\n\n- **`did:key` identity**: each agent gets a persistent Ed25519 identity, exposed as a W3C DID.\n- **W3C Verifiable Credentials**: every memory is signed with `eddsa-jcs-2022` Data Integrity proofs.\n- **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.\n- **Hash-chained transparency log**: append-only JSONL with SHA-256 chaining, a signed Merkle tree head, and RFC 6962-style inclusion receipts.\n- **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.\n- **Poison-resistance**: altered or injected memories fail verification and are rejected before influencing the agent.\n\n```bash\ncogmem verify # check all memories and the log head\ncogmem receipt # prove a memory is in the signed log\ncogmem revoke # revoke a memory (Bitstring Status List)\ncogmem status-list # emit the signed revocation status-list credential\n```\n\nSee [PROVENANCE.md](./PROVENANCE.md) for the full specification.\n\n**Verify the C2PA sample yourself:**\n\n```bash\n# examples/c2pa-agent-credential/ is a real signed C2PA manifest\n# whose agent identity validates in c2patool\n./examples/c2pa-agent-credential/verify.sh\n```\n\nThis 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.\n\n\n\n## Standards alignment\n\ncogmem 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.\n\n| Standard | What cogmem implements | Status |\n|---|---|---|\n| [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 |\n| [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 |\n| [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 |\n| [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 |\n| [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 |\n| [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 |\n| [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 |\n| [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` |\n\n**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.\n\n## Privacy\n\ncogmem 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.\n\nThe **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.**\n\n## Part of the Agent-Provenance Stack\n\ncogmem is one component of the WritersLogic verifiable agent-provenance pipeline — agent identity, memory, reasoning, and signed output, cryptographically bound end to end.\n\n| Project | Role |\n|---|---|\n| **cogmem (this repo)** | Agent identity (CAWG credential) + verifiable, tamper-evident memory (COSE/SCITT) |\n| [crosstalk](https://github.com/writerslogic/crosstalk) | Multi-model orchestrator; signs each turn's reasoning/orchestration audit |\n| [holographic-memory](https://github.com/writerslogic/holographic-memory) | Durable holographic memory store; cross-verifies signed statements and agent identity |\n| WritersProof | C2PA producer: binds identity + memory + reasoning to the signed asset |\n\nAll four share one substrate — COSE_Sign1 / SCITT signed statements (Ed25519) and W3C DID identity — specified in [UNIFIED-PROVENANCE.md](./UNIFIED-PROVENANCE.md).\n\n## Security\n\nFound a vulnerability? Please report it privately — see [SECURITY.md](./SECURITY.md).\n\n## License\n\nApache-2.0 — see [LICENSE](./LICENSE).\n",
"bytes": 17426,
"sha": "81d8f7c32f5cbde005d816ffbbd9b38f3e8628d0c1ce7861f96072514ec63bb1",
"repo_slug": "writerslogic/cogmem",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_writerslogic_cogmem_0e15dcad/readme"
}
![\"cogmem](\"https://raw.githubusercontent.com/writerslogic/cogmem/main/assets/logo-spin.gif\"){kind=logo}
\n\n