Demonstrate released agent memory with a reproducible project lesson

publication/agent-memory-hooks/README.md

@@ -0,0 +1,9 @@
+# Terraphim memory and hooks publication sources
+
+Two independent releases of reader-facing content: memory on 13 October 2026 and hooks on 14 October, both at 11:00 BST. LinkedIn copy remains draft-only. The existing editor/grep campaign is separate.
+
+The memory example uses publicly downloaded agent v1.21.20, verified archive signatures/checksums, and actual saved outputs. The downloadable ZIP contains its complete fixture, isolated runner, release identities, receipts and checksums. The final video is 77 seconds with natural-rate synthetic British female Emma narration.
+
+The hooks example is qualified separately on agent v1.21.19 and OpenCode2.0.20: real failure, explicit reviewed promotion, standalone hook output, then actual host execution through the included local adapter. It must retain that scope and its public-data-only redaction limitation.
+
+`campaign.json` is the operator ledger, when present. Preparation or a scheduled wakeup does not mean a page or post is live. Per-channel drafts and evidence stay separate from verified published receipts.

publication/agent-memory-hooks/memory/package/README.md

@@ -0,0 +1,79 @@
+# Harbour: save a lesson and find it next time
+
+This public example captures an actual instruction, recovers it in new processes,
+and retrieves it through an explicit project knowledge graph. It uses
+terraphim-agent **1.21.20**. Earlier 1.21.19 cannot capture supplied lesson text.
+
+## Requirements
+
+- Python 3.9 or later and `rg` (ripgrep) on PATH; the local Markdown KG loader uses it.
+- The released `terraphim-agent` for your platform. Download it and SHA256SUMS from:
+  https://github.com/terraphim/terraphim-clients/releases/tag/v1.21.20
+- Verify the archive against the release's SHA256SUMS before extracting it.
+  `released-binaries.json` also pins the extracted binaries accepted by this example.
+- No model-provider account is needed for this memory walkthrough. There is no
+  generated answer and no coding-host execution in this example.
+
+## Run every check
+
+From this extracted folder, substituting your real binary path:
+
+```sh
+python3 reproduce.py --agent /path/to/terraphim-agent --output ./harbour-run
+```
+
+The output folder must not exist. The script checks the binary's exact version
+and hash, prepares public input and scoped settings, then starts ten independent
+CLI processes. It never changes HOME or installs hooks. It writes only inside
+that new output folder. If any command or assertion fails, it exits nonzero.
+
+Expected result: `verification.json` says PASS, with qualification
+`released-binary`. One exact saved lesson is retrieved for `validate brief` by
+Brief Reviewer. The unrelated query, Finance Reviewer and separate empty store
+return zero. `memory apply` previews proposed context; it executes nothing.
+
+Inspect `outputs/*.stdout.json` for actual CLI responses, `execution-receipts.json`
+for argv/stdout/stderr/exit codes and `data/terraphim/evolution/cli-agent.json`
+for the persisted store. `recorded/` contains the publication's observed outputs;
+your identifiers and timestamps will naturally differ.
+
+## Walk through the commands yourself
+
+Use another fresh folder. Preparation does not capture memory:
+
+```sh
+python3 reproduce.py --agent /path/to/terraphim-agent --output ./manual-run --prepare-only
+cd manual-run/fixture
+export TERRAPHIM_DEFAULT_DATA_PATH="$(cd .. && pwd)/data"
+export TERRAPHIM_SETTINGS_PATH="$(cd .. && pwd)/settings"
+```
+
+Put the same verified binary on PATH, or replace `terraphim-agent` below with its
+full path. Check `terraphim-agent --version` reports 1.21.20, then run:
+
+```sh
+terraphim-agent --format json memory capture --file lesson.md --provenance-tag harbour-public-brief-v1
+terraphim-agent --format json memory list
+terraphim-agent --format json memory show MEMORY_ID_FROM_CAPTURE
+terraphim-agent memory export --format json --output memories.json
+terraphim-agent --config ../config.json memory retrieve 'validate brief' --role 'Brief Reviewer' --format json
+terraphim-agent --config ../config.json memory retrieve 'volcanic eruption' --role 'Brief Reviewer' --format json
+terraphim-agent --config ../config.json memory retrieve 'validate brief' --role 'Finance Reviewer' --format json
+```
+
+Every command exits; the next invocation reads the saved file in a new process.
+The knowledge graph is in `fixture/kg/`. Its `synonyms::` definitions are explicit,
+reviewable terminology. Saving a memory does not automatically create concepts
+or copy the item to the separate learning-corrections store.
+
+## Scope and interpretation
+
+Roles filter graph retrieval; they do not enforce confidentiality. Separate data
+roots select separate stores, and ordinary filesystem permissions still apply.
+The lesson is preserved as supplied, so review your own notes before sharing or
+exporting them. This sample contains no private data or credentials. Graph
+retrieval depends on concept co-occurrence; the note deliberately connects Brief
+validation with Project brief. No token savings or host execution are claimed.
+
+The `--candidate` switch is only for engineering checks and labels results
+`candidate-only`; those results do not qualify as released-binary evidence.

publication/agent-memory-hooks/memory/package/fixture/brief.md

@@ -0,0 +1,5 @@
+# Harbour project brief
+
+Decision: validate the public brief before publication.
+Risk: missing the owner of the decision.
+Owner: Harbour team.

publication/agent-memory-hooks/memory/package/fixture/kg/brief/brief-validation.md

@@ -0,0 +1,4 @@
+# Brief validation
+synonyms:: validate brief, brief validation, --check
+
+Validate the public project brief before publication.

publication/agent-memory-hooks/memory/package/fixture/kg/brief/project-brief.md

@@ -0,0 +1,4 @@
+# Project brief
+synonyms:: public project brief, brief.md, project brief
+
+The brief records a decision, risk and owner.

publication/agent-memory-hooks/memory/package/fixture/kg/finance/budget-review.md

@@ -0,0 +1,4 @@
+# Budget review
+synonyms:: budget, spending review
+
+Review the project budget.

publication/agent-memory-hooks/memory/package/fixture/kg/finance/grant.md

@@ -0,0 +1,4 @@
+# Grant
+synonyms:: funding, finance grant
+
+Review the grant funding.

publication/agent-memory-hooks/memory/package/fixture/lesson.md

@@ -0,0 +1 @@
+Validate the Harbour project brief with python3 validate-brief.py --check. Keep the source decisions in brief.md intact.

publication/agent-memory-hooks/memory/package/fixture/validate-brief.py

@@ -0,0 +1,10 @@
+from pathlib import Path
+import argparse, json
+parser=argparse.ArgumentParser(description="Validate the fictional Harbour project brief")
+parser.add_argument("--check",action="store_true",required=True)
+args=parser.parse_args()
+text=Path("brief.md").read_text()
+assert all(x in text for x in ("Decision:","Risk:","Owner:")), "Brief is missing a required field"
+result={"project":"Harbour", "status":"valid", "fields":["Decision","Risk","Owner"]}
+Path("validation.json").write_text(json.dumps(result,indent=2)+"\n")
+print(json.dumps(result))

publication/agent-memory-hooks/memory/package/released-binaries.json

@@ -0,0 +1,62 @@
+{
+  "version": "1.21.20",
+  "releaseUrl": "https://github.com/terraphim/terraphim-clients/releases/tag/v1.21.20",
+  "sourceSha": "d55d373ec2eb100d334712f086dc95a2829856e7",
+  "qualification": "downloaded from public release URLs; SHA256SUMS and embedded signatures verified",
+  "binaries": [
+    {
+      "target": "aarch64-apple-darwin",
+      "archive": "terraphim-agent-1.21.20-aarch64-apple-darwin.tar.gz",
+      "archiveUrl": "https://github.com/terraphim/terraphim-clients/releases/download/v1.21.20/terraphim-agent-1.21.20-aarch64-apple-darwin.tar.gz",
+      "archiveSha256": "e7e075d47e79b03f41f646ca388d8c7104065cfb8ea0966761b1f6ae796166bd",
+      "binarySha256": "bff31dc42d6d1a99bf51291039d7719c6a48c2326e582e5e24eaa1eaf11e17ec",
+      "bytes": 8973418,
+      "embeddedSignature": "PASS"
+    },
+    {
+      "target": "aarch64-unknown-linux-musl",
+      "archive": "terraphim-agent-1.21.20-aarch64-unknown-linux-musl.tar.gz",
+      "archiveUrl": "https://github.com/terraphim/terraphim-clients/releases/download/v1.21.20/terraphim-agent-1.21.20-aarch64-unknown-linux-musl.tar.gz",
+      "archiveSha256": "cf09f161ff42180308509d8e9b43b66c94bedd3801987cd1112b38b3718b5789",
+      "binarySha256": "5ae520c7034dd125dc6ccb0f6a2f7233794e4bef254381f292566827988f9c52",
+      "bytes": 9393380,
+      "embeddedSignature": "PASS"
+    },
+    {
+      "target": "universal-apple-darwin",
+      "archive": "terraphim-agent-1.21.20-universal-apple-darwin.tar.gz",
+      "archiveUrl": "https://github.com/terraphim/terraphim-clients/releases/download/v1.21.20/terraphim-agent-1.21.20-universal-apple-darwin.tar.gz",
+      "archiveSha256": "3b8766759eb227e0e99fe35cf63bbe7d39eb225dfb5b0b89e6a2b32fc3404fda",
+      "binarySha256": "ced47028f352f3be126c1ad013abd5ad04bb0d5f21438a6aa55730f101caded6",
+      "bytes": 18720628,
+      "embeddedSignature": "PASS"
+    },
+    {
+      "target": "x86_64-apple-darwin",
+      "archive": "terraphim-agent-1.21.20-x86_64-apple-darwin.tar.gz",
+      "archiveUrl": "https://github.com/terraphim/terraphim-clients/releases/download/v1.21.20/terraphim-agent-1.21.20-x86_64-apple-darwin.tar.gz",
+      "archiveSha256": "6928d1e60fc30a7a9eb4eec3f6429d5a9774370cea967ff2a9d088c380b1615c",
+      "binarySha256": "61ed0e6737c0011a3a0805ffd9383c189b889f2669458ce4fc7b95260b534e90",
+      "bytes": 9749512,
+      "embeddedSignature": "PASS"
+    },
+    {
+      "target": "x86_64-unknown-linux-gnu",
+      "archive": "terraphim-agent-1.21.20-x86_64-unknown-linux-gnu.tar.gz",
+      "archiveUrl": "https://github.com/terraphim/terraphim-clients/releases/download/v1.21.20/terraphim-agent-1.21.20-x86_64-unknown-linux-gnu.tar.gz",
+      "archiveSha256": "c58f4c384a29e2d5dc43b46c14741b6d083699d03e5ab6b6b15b4f5c1fd9a07f",
+      "binarySha256": "6c1ce6b3c939888021991c400da6281bafacb6ffe9b63c872a895281d633c2f2",
+      "bytes": 10335616,
+      "embeddedSignature": "PASS"
+    },
+    {
+      "target": "x86_64-unknown-linux-musl",
+      "archive": "terraphim-agent-1.21.20-x86_64-unknown-linux-musl.tar.gz",
+      "archiveUrl": "https://github.com/terraphim/terraphim-clients/releases/download/v1.21.20/terraphim-agent-1.21.20-x86_64-unknown-linux-musl.tar.gz",
+      "archiveSha256": "242c3a72849d3e905c3af6359002fb7473c900df2f4c87ccdebe80c0c538e4ce",
+      "binarySha256": "22795761e381a5cf3bac973aa2f255a3749acd9677c3dddbe54ff776d2645655",
+      "bytes": 10189950,
+      "embeddedSignature": "PASS"
+    }
+  ]
+}

publication/agent-memory-hooks/memory/package/reproduce.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""Recover an authored lesson using a verified released Terraphim agent."""
+import argparse
+import datetime
+import hashlib
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import time
+
+BASE = Path(__file__).resolve().parent
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--agent", required=True, type=Path)
+    parser.add_argument("--output", required=True, type=Path, help="New directory for this run")
+    parser.add_argument("--candidate", action="store_true", help="Engineering check only; never release evidence")
+    parser.add_argument("--prepare-only", action="store_true", help="Prepare an isolated run for the manual walkthrough without capturing a lesson")
+    args = parser.parse_args()
+    agent = args.agent.resolve(strict=True)
+    binary_hash = hashlib.sha256(agent.read_bytes()).hexdigest()
+    version = subprocess.check_output([str(agent), "--version"], text=True).strip()
+    if version != "terraphim-agent 1.21.20":
+        raise SystemExit(f"Expected terraphim-agent 1.21.20, got {version}")
+    if not args.candidate:
+        identities = json.loads((BASE / "released-binaries.json").read_text())
+        if binary_hash not in [item["binarySha256"] for item in identities["binaries"]]:
+            raise SystemExit("Binary checksum is not in this example's verified release identities")
+    root = args.output.resolve()
+    root.mkdir(parents=True, exist_ok=False)
+    shutil.copytree(BASE / "fixture", root / "fixture")
+    fixture = root / "fixture"
+    for name in ("settings", "data", "empty-data", "dashmap", "sqlite", "outputs"):
+        (root / name).mkdir()
+
+    def role(name, key):
+        return dict(shortname=key, name=name, relevance_function="terraphim-graph",
+                    terraphim_it=True, theme="lumen", kg=dict(automata_path=None,
+                    knowledge_graph_local=dict(input_type="markdown", path=str(fixture / "kg" / key)),
+                    public=False, publish=False), haystacks=[], llm_provider=None,
+                    llm_auto_summarize=False, extra={})
+
+    config = dict(id="Server", global_shortcut="Ctrl+Shift+T",
+                  roles={"Brief Reviewer": role("Brief Reviewer", "brief"),
+                         "Finance Reviewer": role("Finance Reviewer", "finance")},
+                  default_role="Brief Reviewer", selected_role="Brief Reviewer")
+    (root / "config.json").write_text(json.dumps(config, indent=2) + "\n")
+    quoted = lambda path: json.dumps(str(path))
+    (root / "settings/settings.toml").write_text(f'''server_hostname = "127.0.0.1:8000"
+api_endpoint = "http://localhost:8000/api"
+initialized = "true"
+default_data_path = {quoted(root / 'data')}
+role_config = {quoted(root / 'config.json')}
+[profiles.dashmap]
+type = "dashmap"
+root = {quoted(root / 'dashmap')}
+[profiles.sqlite]
+type = "sqlite"
+datadir = {quoted(root / 'sqlite')}
+connection_string = {quoted(root / 'sqlite/terraphim.db')}
+table = "terraphim_kv"
+''')
+    if args.prepare_only:
+        print(f"Prepared {root}. No memory captured. See README.md for the scoped manual commands.")
+        return
+    records = []
+
+    def run(label, command, store="data"):
+        env = os.environ.copy()
+        for key in ("GH_TOKEN", "GITHUB_TOKEN", "OPENAI_API_KEY", "ANTHROPIC_API_KEY", "OPENROUTER_API_KEY"):
+            env.pop(key, None)
+        env["TERRAPHIM_DEFAULT_DATA_PATH"] = str(root / store)
+        env["TERRAPHIM_SETTINGS_PATH"] = str(root / "settings")
+        argv = [str(agent), "--format", "json", "--config", str(root / "config.json"), *command]
+        start = time.monotonic()
+        process = subprocess.run(argv, cwd=fixture, env=env, text=True, capture_output=True, timeout=90)
+        record = dict(label=label, argv=argv, store=store, exitCode=process.returncode,
+                      stdout=process.stdout, stderr=process.stderr,
+                      seconds=round(time.monotonic() - start, 3),
+                      utc=datetime.datetime.now(datetime.timezone.utc).isoformat())
+        records.append(record)
+        (root / "outputs" / (label + ".stdout.json")).write_text(process.stdout)
+        (root / "outputs" / (label + ".stderr.txt")).write_text(process.stderr)
+        (root / "execution-receipts.json").write_text(json.dumps(records, indent=2) + "\n")
+        if process.returncode:
+            raise RuntimeError(f"{label} failed: {process.stderr}")
+        return json.loads(process.stdout)
+
+    baseline = run("before-capture", ["memory", "list"])
+    captured = run("capture", ["memory", "capture", "--file", "lesson.md", "--provenance-tag", "harbour-public-brief-v1"])
+    memory_id = captured["memory_id"]
+    shown = run("reopened", ["memory", "show", memory_id, "--json"])
+    listed = run("listed", ["memory", "list"])
+    exported = run("exported", ["memory", "export", "--format", "json"])
+    positive = run("retrieved", ["memory", "retrieve", "validate brief", "--role", "Brief Reviewer", "--format", "json"])
+    negative = run("unrelated-query", ["memory", "retrieve", "volcanic eruption", "--role", "Brief Reviewer", "--format", "json"])
+    other_role = run("other-role", ["memory", "retrieve", "validate brief", "--role", "Finance Reviewer", "--format", "json"])
+    empty = run("separate-store", ["memory", "retrieve", "validate brief", "--role", "Brief Reviewer", "--format", "json"], "empty-data")
+    preview = run("context-preview", ["memory", "apply", "--role", "Brief Reviewer", "--prompt", "validate brief"])
+    lesson = (fixture / "lesson.md").read_text()
+    checks = dict(emptyBaseline=baseline["count"] == 0,
+                  exactNewProcessReadback=shown["memory_item"]["content"] == lesson,
+                  listPersistence=listed["count"] == 1,
+                  exactExport=any(item["content"] == lesson for item in exported["memory_items"]),
+                  conceptRetrieval=positive["count"] == 1 and positive["items"][0]["id"] == memory_id and positive["items"][0]["content"] == lesson,
+                  unrelatedQuery=negative["count"] == 0, otherRole=other_role["count"] == 0,
+                  separateStore=empty["count"] == 0,
+                  proposedContext=preview["retrieved_items"] == 1 and preview["injected_bytes"] > 0)
+    result = dict(status="PASS" if all(checks.values()) else "FAIL", checks=checks,
+                  qualification="candidate-only" if args.candidate else "released-binary",
+                  binaryVersion=version, binarySha256=binary_hash, memoryId=memory_id,
+                  lesson=lesson, processCount=len(records),
+                  note="Every command is a fresh process. Roles filter retrieval; they are not access-control boundaries. Apply is a preview, not execution.")
+    (root / "verification.json").write_text(json.dumps(result, indent=2) + "\n")
+    print(json.dumps(result, indent=2))
+    if not all(checks.values()):
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()