cogmem 2.7.0__tar.gz

cogmem-2.7.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 David Condrey
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cogmem-2.7.0/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: cogmem
+Version: 2.7.0
+Summary: A self-improving, verifiable memory layer for AI coding agents.
+Author: WritersLogic
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/writerslogic/cogmem
+Project-URL: Issues, https://github.com/writerslogic/cogmem/issues
+Keywords: mcp,agent-memory,provenance,did,scitt,verifiable-credentials
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=49.0.0
+Requires-Dist: cbor2>=5.9.0
+Provides-Extra: recall
+Requires-Dist: fastembed>=0.8.0; extra == "recall"
+Requires-Dist: numpy>=1.26; extra == "recall"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/writerslogic/cogmem/main/assets/logo-spin.gif" width="200" alt="cogmem">
+</p>
+
+# cogmem
+
+[![CI](https://github.com/writerslogic/cogmem/actions/workflows/ci.yml/badge.svg)](https://github.com/writerslogic/cogmem/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org)
+[![MCP](https://img.shields.io/badge/MCP-compatible-7c3aed.svg)](https://modelcontextprotocol.io)
+[![cogmem MCP server](https://glama.ai/mcp/servers/writerslogic/cogmem/badges/score.svg)](https://glama.ai/mcp/servers/writerslogic/cogmem)
+[![W3C Verifiable Credentials](https://img.shields.io/badge/W3C-Verifiable%20Credentials-005a9c.svg)](https://www.w3.org/TR/vc-data-model-2.0/)
+[![SCITT](https://img.shields.io/badge/IETF-SCITT--style%20log-005a9c.svg)](https://datatracker.ietf.org/wg/scitt/about/)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![local-first recall](https://img.shields.io/badge/local--first-recall%20runs%20on%20your%20machine-111827.svg)](#privacy)
+
+**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)).
+
+[![cogmem MCP server](https://glama.ai/mcp/servers/writerslogic/cogmem/badges/card.svg)](https://glama.ai/mcp/servers/writerslogic/cogmem)
+
+## 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 <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:
+
+```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.
+
+<details>
+<summary><strong>Why cogmem?</strong> -- learns from outcomes, models failure modes, verifiable memory</summary>
+
+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.
+
+</details>
+
+<details>
+<summary><strong>Features</strong> -- two-layer memory, outcome feedback, self-model, project state, cross-project narrative, self-regulation, verifiable credentials</summary>
+
+- **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).
+
+</details>
+
+<details>
+<summary><strong>Verifiable Memory</strong> -- did:key identity, W3C VC, COSE/SCITT, hash-chained log, poison-resistance</summary>
+
+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.
+- **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 <memory-id> # prove a memory is in the signed log
+```
+
+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.
+
+</details>
+
+## 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).
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE).