Saltglass

Saltglass is an agent knowledge crystallization & governance platform. It turns raw agent session transcripts into crystals — signed, verifiable units of reusable knowledge — and governs their lifecycle: crystallize → approve → sign → verify → expire.

Named after the principle of knowledge crystallizing out of raw conversation, Saltglass gives agents a provenance-guaranteed memory: every crystal is anchored to its source transcript, signed with Ed25519, chained to its siblings, and automatically expired by half-life unless a human reverifies it.

Why

Agents accumulate knowledge in conversation logs that are unstructured, unverified, and unmanageable. Teams need:

• Provenance — which crystal came from which session, anchored to source lines.
• Integrity — cryptographic proof a crystal hasn't been tampered with (content hash + Ed25519 signatures).
• Governance — a human approve/reject gate, immutable chain of decisions, expiry by half-life.
• Portability — crystals export as agent-loadable YAML + SKILL.md and human-readable SRS + retro, all age-encrypted at rest.

Screenshots

Web console — governance dashboard (dark theme)

Web console — light theme

CLI — crystal registry & governance stats

CLI — provenance verification & audit log

---

Architecture

session transcripts (markdown / JSONL / OpenClaw)
        │
        ▼
   crystallize ───► proposals (candidates with kinds, anchors, confidence)
        │
        ▼
   approve / reject  ◄── human reviewer (web console / CLI / API / SDK)
        │
        ▼
   sign ───► Ed25519 chain link appended to chain (append-only)
        │
        ▼
   materialize ───► vault assets (skills/*.yaml + SKILL.md, srs/*.md, retros/*.md)
        │
        ▼
   verify ───► 6 checks: exists, content_hash, chain_signature,
               chain_linkage, asset_signatures, source_anchors
        │
        ▼
   expire ───► half-life expiry / duplicates / contradictions ──► reverify

Components

Component	Path	Purpose
Core library	saltglass/	crystallize, governance, signing, storage, verify, expiry, transcripts, providers
REST API + web console	saltglass/server.py, web/	FastAPI server, React (Vite + TS) dark/light console
CLI	saltglass/cli.py	headless governance workflows
SDK	sdk/saltglass_sdk/	Crystallizer (standalone), SaltglassClient (REST), VerifyGate (consume-time check)
Tests	tests/	109 unit + E2E tests, 86% coverage

---

Quickstart

1. Install

cd /workspace
pip install --break-system-packages -e .
pip install --break-system-packages -r requirements.txt -r requirements-dev.txt

2. Run the server (auto-initializes a fresh vault)

SALTGLASS_VAULT_DIR=/tmp/sg-vault SALTGLASS_LLM_PROVIDER=rules SALTGLASS_PORT=8766 \
  python3 -m uvicorn saltglass.server:app --host 0.0.0.0 --port 8766

• SALTGLASS_LLM_PROVIDER=rules → deterministic offline extraction (no API key needed).
• SALTGLASS_LLM_PROVIDER=ollama|openai → LLM extraction (USER_LLM_API_KEY for openai).
• Web console: http://localhost:8766/ (all 9 pages).

3. CLI flow

# List candidates from transcripts
python3 -m saltglass.cli crystallize examples/transcripts/*.jsonl --vault-dir /tmp/sg-vault --provider rules

# Approve and sign a proposal
python3 -m saltglass.cli approve <CRYSTAL_ID> --vault-dir /tmp/sg-vault --reviewer you

# Verify integrity
python3 -m saltglass.cli verify <CRYSTAL_ID> --vault-dir /tmp/sg-vault

# Run expiry maintenance
python3 -m saltglass.cli expire --vault-dir /tmp/sg-vault --json

4. SDK drop-in (the pattern Sphinx uses)

See examples/sdk_embed_demo.py:

from saltglass_sdk import Crystallizer, SaltglassClient, VerifyGate

candidates = Crystallizer(provider="rules").crystallize_text("...")
with SaltglassClient("http://localhost:8766") as c:
    proposals = c.crystallize(["session.jsonl"])
gate = VerifyGate(public_key_file="vault/signing-key.pub")
assert gate.verify_file("vault/skills/crystal.yaml").valid

Verification model

Each crystal passes 6 checks (verify.py):

1. exists — crystal row and vault assets present.
2. content_hash — recomputed payload hash matches the signed hash.
3. chain_signature — Ed25519 over prev_hash + content_hash.
4. chain_linkage — the crystal's chain is continuous (append-only, no holes).
5. asset_signatures — every exported asset file has a valid .sig sidecar.
6. source_anchors — anchor turn indices resolve inside the source transcript.

Lifecycle & half-life

• Proposals expire from the queue after proposal_ttl_days.
• Approved crystals expire after ttl_days unless reverified.
• expire maintenance flags: expired, duplicates (same content hash), contradictions (kind + title conflicts across chains).

Project layout

saltglass/        core library (16 modules)
sdk/              saltglass_sdk (crystallizer, client, gate)
web/              React + Vite + TS console
examples/         sample transcripts + SDK embed demo
tests/            pytest suite (12 files)
docs/             design notes
TEST_REPORT.md    full test & verification report

Testing

cd /workspace
python3 -m pytest tests/ --cov=saltglass --cov-report=term   # 109 passed, 86% coverage

Full details in TEST_REPORT.md.