claimkeep 0.2.0__tar.gz

claimkeep-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ravshan Nuraliev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claimkeep-0.2.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.1
+Name: claimkeep
+Version: 0.2.0
+Summary: Continuous memory for Claude Code context compaction.
+Author: Ravshan Nuraliev
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# ClaimKeep
+
+Continuous memory for Claude Code. When the context window compacts, the summary keeps the gist
+and drops the specifics — numbers, paths, ids, and decisions that were later reversed. ClaimKeep
+runs before compaction, takes the agent's own confidence-marked statements **verbatim** instead of
+paraphrasing them, and re-injects them afterwards. It augments native compaction rather than
+replacing it, so it is never worse than the default.
+
+The idea it rests on: a calibration marker such as `Ship Friday [C:80%]` turns any factual sentence
+into a claim the agent already selected and already rated. No guessing what mattered. A marker-free
+regex floor still catches paths, ids, and decision lines when a transcript has no markers at all.
+The brief contract is frozen and documented in [docs/BRIEF_SCHEMA.md](docs/BRIEF_SCHEMA.md).
+
+Measured in production, not on a benchmark: **at least 326 compactions survived on two independent
+platforms — 283 of them carried facts forward (86.8%), with one confirmed loss.**
+Codex platform: 237 compactions, 84.4% carried facts, 2842 claims retained, one agent.
+Claude Code fleet: 89 compactions, 93.3% carried facts, one real loss in 89 (98.9% clean).
+"At least" is literal: only 5 of the 7 fleet agents write the counters, so the fleet figure is a
+floor rather than a total. Loss is graded on the fleet side only — the Codex side counts
+compactions and claims but does not classify a zero. Measurement windows are 19 and 8 days, ending
+2026-08-10; the mechanism has been running longer than the instrumentation that counts it.
+
+Read the figures above as a property of this setup rather than of the tool on its own: every agent
+measured here already carries calibration markers in its system prompt, and marker density is what
+the mechanism feeds on. A clean install, with no markers in the prompt, is a different environment;
+that second figure is being measured separately and is not in this README yet. Until it is, treat
+these numbers as an instrumented-fleet result, not as what a fresh install should expect.
+
+Method and defensible lift numbers are in the paper, *"Continuous Memory for Multi-Agent
+Infrastructure: A Calibration-Density Law for Surviving Context Compaction"* (Ravshan Nuraliev,
+2026) — <https://zenodo.org/records/20819013>. Please cite the Zenodo record if you use ClaimKeep.
+
+## Install
+
+```bash
+claude plugin marketplace add rushnur88/claimkeep
+claude plugin install claimkeep
+```
+
+Two commands, and that is the whole install — no `pip install` step, no build, no dependencies:
+the hooks run the bundled package straight from the plugin directory. Requirements are Claude Code
+and Python 3.9+.
+
+If you would rather have the CLI on your PATH as well, `pip install .` or `npm install -g .` both
+work, and the hooks will prefer the installed binary when they find one.
+
+Note that a memory layer reads your transcript. ClaimKeep runs a secret and PII redaction pass
+before any text enters a brief (API keys, tokens, private-key blocks, JWTs, bearer tokens,
+`key=value` secrets, emails), on by default via `Config.redact`. It targets well-known shapes and
+is defense in depth, not a guarantee — it is not a reason to paste credentials into a session.
+
+## Verify it works
+
+Run the hook by hand against the bundled sample transcript. This is exactly what Claude Code runs
+on `PreCompact`:
+
+```bash
+CLAIMKEEP_BRIEF_DIR=/tmp/ck-check ./scripts/precompact.sh <<'EOF'
+{"transcript_path": "examples/sample_transcript.jsonl", "session_id": "verify-001"}
+EOF
+```
+
+It prints the path of the brief it wrote. Confirm the brief exists and holds a claim:
+
+```bash
+cat /tmp/ck-check/*.json
+```
+
+You should see a `claims` array with `Ship ClaimKeep package Friday` at confidence `0.8`, plus a
+`supplement` section with the ids, paths, and decision lines the floor picked up.
+
+Then check the other half — re-injection:
+
+```bash
+CLAIMKEEP_BRIEF_DIR=/tmp/ck-check CLAUDE_HOOK_EVENT_NAME=PostCompact ./scripts/postcompact.sh <<< '{}'
+```
+
+It emits the `hookSpecificOutput.additionalContext` payload Claude Code feeds back into the fresh
+window. If both commands produce output, the plugin is wired correctly.
+
+Both hooks are fail-open on purpose — a memory layer must never block compaction, so they always
+exit `0`. That means a broken install cannot stall your session, but it also means you should run
+the two checks above once rather than assume silence equals success. Errors go to stderr.
+
+Full test suite: `python3 -m unittest discover -s tests` (92 tests, standard library only).
+
+## See what it did
+
+`stats` reports across every brief you have stored, not just the last one:
+
+```bash
+claimkeep stats          # human-readable
+claimkeep stats --json   # same numbers, machine-readable
+```
+
+It answers the question a single brief cannot: is the layer still earning its keep. Two lines matter
+most. **Retractions** counts claims that overturn an earlier statement — a memory layer that keeps a
+refuted claim and drops its refutation is worse than no memory at all. **Confidence-marked** is the
+share of claims that arrived already carrying a `[C:NN%]` marker; when that share falls, the
+convention is eroding and the calibration harvester quietly runs out of input.
+
+If your briefs came from a different collector, `stats` reports retractions as *not measurable*
+rather than as zero. A zero you cannot distinguish from "never happened" is the failure mode this
+package is built around, and the report is not allowed to produce one.
+
+---
+
+Developed by Ravshan Nuraliev. MIT licensed.

claimkeep-0.2.0/README.md

@@ -0,0 +1,108 @@
+# ClaimKeep
+
+Continuous memory for Claude Code. When the context window compacts, the summary keeps the gist
+and drops the specifics — numbers, paths, ids, and decisions that were later reversed. ClaimKeep
+runs before compaction, takes the agent's own confidence-marked statements **verbatim** instead of
+paraphrasing them, and re-injects them afterwards. It augments native compaction rather than
+replacing it, so it is never worse than the default.
+
+The idea it rests on: a calibration marker such as `Ship Friday [C:80%]` turns any factual sentence
+into a claim the agent already selected and already rated. No guessing what mattered. A marker-free
+regex floor still catches paths, ids, and decision lines when a transcript has no markers at all.
+The brief contract is frozen and documented in [docs/BRIEF_SCHEMA.md](docs/BRIEF_SCHEMA.md).
+
+Measured in production, not on a benchmark: **at least 326 compactions survived on two independent
+platforms — 283 of them carried facts forward (86.8%), with one confirmed loss.**
+Codex platform: 237 compactions, 84.4% carried facts, 2842 claims retained, one agent.
+Claude Code fleet: 89 compactions, 93.3% carried facts, one real loss in 89 (98.9% clean).
+"At least" is literal: only 5 of the 7 fleet agents write the counters, so the fleet figure is a
+floor rather than a total. Loss is graded on the fleet side only — the Codex side counts
+compactions and claims but does not classify a zero. Measurement windows are 19 and 8 days, ending
+2026-08-10; the mechanism has been running longer than the instrumentation that counts it.
+
+Read the figures above as a property of this setup rather than of the tool on its own: every agent
+measured here already carries calibration markers in its system prompt, and marker density is what
+the mechanism feeds on. A clean install, with no markers in the prompt, is a different environment;
+that second figure is being measured separately and is not in this README yet. Until it is, treat
+these numbers as an instrumented-fleet result, not as what a fresh install should expect.
+
+Method and defensible lift numbers are in the paper, *"Continuous Memory for Multi-Agent
+Infrastructure: A Calibration-Density Law for Surviving Context Compaction"* (Ravshan Nuraliev,
+2026) — <https://zenodo.org/records/20819013>. Please cite the Zenodo record if you use ClaimKeep.
+
+## Install
+
+```bash
+claude plugin marketplace add rushnur88/claimkeep
+claude plugin install claimkeep
+```
+
+Two commands, and that is the whole install — no `pip install` step, no build, no dependencies:
+the hooks run the bundled package straight from the plugin directory. Requirements are Claude Code
+and Python 3.9+.
+
+If you would rather have the CLI on your PATH as well, `pip install .` or `npm install -g .` both
+work, and the hooks will prefer the installed binary when they find one.
+
+Note that a memory layer reads your transcript. ClaimKeep runs a secret and PII redaction pass
+before any text enters a brief (API keys, tokens, private-key blocks, JWTs, bearer tokens,
+`key=value` secrets, emails), on by default via `Config.redact`. It targets well-known shapes and
+is defense in depth, not a guarantee — it is not a reason to paste credentials into a session.
+
+## Verify it works
+
+Run the hook by hand against the bundled sample transcript. This is exactly what Claude Code runs
+on `PreCompact`:
+
+```bash
+CLAIMKEEP_BRIEF_DIR=/tmp/ck-check ./scripts/precompact.sh <<'EOF'
+{"transcript_path": "examples/sample_transcript.jsonl", "session_id": "verify-001"}
+EOF
+```
+
+It prints the path of the brief it wrote. Confirm the brief exists and holds a claim:
+
+```bash
+cat /tmp/ck-check/*.json
+```
+
+You should see a `claims` array with `Ship ClaimKeep package Friday` at confidence `0.8`, plus a
+`supplement` section with the ids, paths, and decision lines the floor picked up.
+
+Then check the other half — re-injection:
+
+```bash
+CLAIMKEEP_BRIEF_DIR=/tmp/ck-check CLAUDE_HOOK_EVENT_NAME=PostCompact ./scripts/postcompact.sh <<< '{}'
+```
+
+It emits the `hookSpecificOutput.additionalContext` payload Claude Code feeds back into the fresh
+window. If both commands produce output, the plugin is wired correctly.
+
+Both hooks are fail-open on purpose — a memory layer must never block compaction, so they always
+exit `0`. That means a broken install cannot stall your session, but it also means you should run
+the two checks above once rather than assume silence equals success. Errors go to stderr.
+
+Full test suite: `python3 -m unittest discover -s tests` (92 tests, standard library only).
+
+## See what it did
+
+`stats` reports across every brief you have stored, not just the last one:
+
+```bash
+claimkeep stats          # human-readable
+claimkeep stats --json   # same numbers, machine-readable
+```
+
+It answers the question a single brief cannot: is the layer still earning its keep. Two lines matter
+most. **Retractions** counts claims that overturn an earlier statement — a memory layer that keeps a
+refuted claim and drops its refutation is worse than no memory at all. **Confidence-marked** is the
+share of claims that arrived already carrying a `[C:NN%]` marker; when that share falls, the
+convention is eroding and the calibration harvester quietly runs out of input.
+
+If your briefs came from a different collector, `stats` reports retractions as *not measurable*
+rather than as zero. A zero you cannot distinguish from "never happened" is the failure mode this
+package is built around, and the report is not allowed to produce one.
+
+---
+
+Developed by Ravshan Nuraliev. MIT licensed.

claimkeep-0.2.0/claimkeep/__init__.py

@@ -0,0 +1,18 @@
+"""ClaimKeep public API."""
+
+from .brief import Brief, Claim, Supplement, make_id, normalize
+from .config import default_config
+from . import harvesters
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "__version__",
+    "Brief",
+    "Claim",
+    "Supplement",
+    "normalize",
+    "make_id",
+    "default_config",
+    "harvesters",
+]

claimkeep-0.2.0/claimkeep/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

claimkeep-0.2.0/claimkeep/brief.py

@@ -0,0 +1,215 @@
+"""Brief schema v1 primitives."""
+
+from __future__ import annotations
+
+import json
+import re
+import hashlib
+import unicodedata
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterable, List, Optional
+
+
+SCHEMA_VERSION = 1
+
+
+def normalize(text: str) -> str:
+    """Normalize text for deterministic id hashing only."""
+    return re.sub(r"\s+", " ", unicodedata.normalize("NFC", text).casefold().strip())
+
+
+def make_id(source_harvester: str, middle: str, text: str) -> str:
+    payload = source_harvester + "|" + middle + "|" + normalize(text)
+    return hashlib.sha1(payload.encode("utf-8")).hexdigest()[:16]
+
+
+@dataclass
+class Claim:
+    text: str
+    confidence: Optional[float]
+    topic: str
+    source_harvester: str
+    ts: Optional[str] = None
+    source_span: Optional[str] = None
+    id: Optional[str] = None
+    # Supersession chain. A later claim on the same topic does NOT delete the
+    # earlier one: the earlier one is marked superseded_by and kept. Dropping it
+    # silently makes a retraction indistinguishable from a fact never stated,
+    # and the reader cannot tell which of two conflicting facts is live.
+    superseded_by: Optional[str] = None
+    supersedes: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        if self.confidence is not None:
+            self.confidence = max(0.0, min(1.0, float(self.confidence)))
+        if self.id is None:
+            self.id = make_id(self.source_harvester, self.topic, self.text)
+
+    @property
+    def is_active(self) -> bool:
+        """True when nothing later has superseded this claim."""
+        return self.superseded_by is None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "text": self.text,
+            "confidence": self.confidence,
+            "topic": self.topic,
+            "source_harvester": self.source_harvester,
+            "ts": self.ts,
+            "source_span": self.source_span,
+            "superseded_by": self.superseded_by,
+            "supersedes": self.supersedes,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Claim":
+        return cls(
+            id=str(data["id"]),
+            text=str(data["text"]),
+            confidence=None if data.get("confidence") is None else float(data["confidence"]),
+            topic=str(data["topic"]),
+            source_harvester=str(data["source_harvester"]),
+            ts=data.get("ts"),
+            source_span=data.get("source_span"),
+            superseded_by=data.get("superseded_by"),
+            supersedes=data.get("supersedes"),
+        )
+
+
+@dataclass
+class Supplement:
+    text: str
+    kind: str
+    source_harvester: str
+    id: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        if self.kind not in {"id", "path", "decision"}:
+            raise ValueError("supplement kind must be one of: id, path, decision")
+        if self.id is None:
+            self.id = make_id(self.source_harvester, self.kind, self.text)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "text": self.text,
+            "kind": self.kind,
+            "source_harvester": self.source_harvester,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Supplement":
+        return cls(
+            id=str(data["id"]),
+            text=str(data["text"]),
+            kind=str(data["kind"]),
+            source_harvester=str(data["source_harvester"]),
+        )
+
+
+@dataclass
+class Brief:
+    claims: List[Claim] = field(default_factory=list)
+    supplement: List[Supplement] = field(default_factory=list)
+    created_utc: Optional[str] = None
+    source: Optional[Dict[str, Any]] = None
+    open_threads: List[str] = field(default_factory=list)
+    last_user_ask: Optional[str] = None
+    narrative: List[str] = field(default_factory=list)
+    schema_version: int = SCHEMA_VERSION
+
+    def __post_init__(self) -> None:
+        if self.schema_version != SCHEMA_VERSION:
+            raise ValueError("unsupported schema_version")
+        self.claims = self._dedup_claims(self.claims)
+        self.supplement = self._dedup_supplement(self.supplement)
+
+    def add_claim(self, claim: Claim) -> None:
+        self.claims.append(claim)
+        self.claims = self._dedup_claims(self.claims)
+
+    def add_supplement(self, supplement: Supplement) -> None:
+        self.supplement.append(supplement)
+        self.supplement = self._dedup_supplement(self.supplement)
+
+    @property
+    def active_claims(self) -> List[Claim]:
+        return [claim for claim in self.claims if claim.is_active]
+
+    @staticmethod
+    def _dedup_claims(claims: Iterable[Claim]) -> List[Claim]:
+        """Collapse exact repeats, mark same-topic history as superseded.
+
+        Two passes. Identical ids are the same claim restated, so only the last
+        occurrence survives. Different claims on the same topic are a change of
+        position over time: the newest stays active and every earlier one is
+        kept with superseded_by pointing at it, newest carrying supersedes back.
+        """
+        latest_by_id: Dict[str, tuple[int, Claim]] = {}
+        for index, claim in enumerate(claims):
+            latest_by_id[str(claim.id)] = (index, claim)
+        ordered = [item for item in sorted(latest_by_id.values(), key=lambda item: item[0])]
+
+        by_topic: Dict[str, List[Claim]] = {}
+        for _, claim in ordered:
+            by_topic.setdefault(claim.topic, []).append(claim)
+
+        for topic_claims in by_topic.values():
+            newest = topic_claims[-1]
+            newest.superseded_by = None
+            if len(topic_claims) > 1:
+                newest.supersedes = topic_claims[-2].id
+            for earlier in topic_claims[:-1]:
+                earlier.superseded_by = newest.id
+        return [claim for _, claim in ordered]
+
+    @staticmethod
+    def _dedup_supplement(supplements: Iterable[Supplement]) -> List[Supplement]:
+        by_id: Dict[str, Supplement] = {}
+        for item in supplements:
+            by_id[str(item.id)] = item
+        return list(by_id.values())
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "schema_version": self.schema_version,
+            "created_utc": self.created_utc,
+            "source": self.source,
+            "claims": [claim.to_dict() for claim in self.claims],
+            "supplement": [item.to_dict() for item in self.supplement],
+            "open_threads": list(self.open_threads),
+            "last_user_ask": self.last_user_ask,
+            "narrative": list(self.narrative),
+        }
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, sort_keys=True, indent=2) + "\n"
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Brief":
+        if data.get("schema_version") != SCHEMA_VERSION:
+            raise ValueError("unsupported schema_version")
+        for key in ("claims", "supplement"):
+            if key not in data:
+                raise ValueError("missing required key: " + key)
+        return cls(
+            schema_version=SCHEMA_VERSION,
+            created_utc=data.get("created_utc"),
+            source=data.get("source"),
+            claims=[Claim.from_dict(item) for item in data.get("claims", [])],
+            supplement=[Supplement.from_dict(item) for item in data.get("supplement", [])],
+            open_threads=list(data.get("open_threads", [])),
+            last_user_ask=data.get("last_user_ask"),
+            narrative=list(data.get("narrative", [])),
+        )
+
+    @classmethod
+    def from_json(cls, text: str) -> "Brief":
+        return cls.from_dict(json.loads(text))
+
+    def render(self) -> str:
+        from .rehydrate import render
+
+        return render(self)