Update README.md

README.md

@@ -10,5 +10,159 @@ pinned: false
 license: other
 short_description: infrastructure, not a toy.
 ---
+# RFTSystems — TrustStack Console
+I don’t do “trust me”. I do receipts.
+
+**TrustStack Console** is a single, clean demo of what “agent infrastructure” should look like when you care about auditability, integrity, and cost control. It combines durable local memory, fast retrieval, tamper-evident logging, per-turn receipts, verification, guardrails, trace artifacts, and one-click audit exports.
+
+Space: https://huggingface.co/spaces/RFTSystems/TrustStack_Console
+
+---
+
+## What this is
+Most agent stacks can store chat logs. That is not the problem.
+
+The problem is **provable influence**:
+- What memory did the agent actually retrieve?
+- What evidence influenced the output?
+- Can you prove the record wasn’t edited after the fact?
+- Can you export a defensible audit bundle?
+
+TrustStack answers those questions with:
+- **Append-only ledger** (events stored as JSONL)
+- **Hash chain integrity** (tamper-evident session history)
+- **SQLite FTS retrieval** (fast lexical recall, no embeddings required)
+- **Per-turn Memory Receipts** (downloadable proof of retrieval + hashes)
+- **Receipt verification** (pass/fail)
+- **Receipt-gated tool execution** (guardrails)
+- **Trace export** (OTel-style trace artifact JSON)
+- **Audit pack export** (ZIP bundle of ledger + receipts + integrity summary)
+- **Token budget calculator** (why fixed retrieval beats replaying history)
+
+---
+
+## How it works (in plain terms)
+1. Every message becomes an **event** appended to the session ledger.
+2. Each event is hashed (`digest`) and chained to the previous event (`chain_hash`).
+3. Retrieval uses **SQLite FTS5** over stored text.
+4. Every assistant turn produces a **receipt** containing:
+   - the query
+   - the retrieved event slices
+   - each slice’s digest + chain hash
+   - prompt hash + response hash
+5. Receipt verification checks that all referenced events exist and that hashes match the stored ledger.
+
+If someone edits history, the chain breaks. Verification fails. Loudly.
+
+---
+
+## Tabs
+### Investor Demo
+One click, full story: store → retrieve → override → generate receipt → verify → export trace → export audit pack.
+
+### Chat
+Live interaction. Stores every turn, retrieves relevant memory slices, generates receipts.
+
+### Verify Receipt
+Upload a receipt JSON and get a pass/fail integrity check.
+
+### Guardrails
+A tool call is blocked unless a supplied receipt verifies. This demonstrates “execution only when evidence checks out”.
+
+### Trace Export
+Each turn produces an OTel-style trace JSON artifact showing what was retrieved and what hashes were produced.
+
+### Audit Pack
+One-click ZIP export: ledger + receipts + integrity summary.
+
+### API Playground
+JSON-in / JSON-out “tool style” calls (write, search, verify, export) for developers.
+
+### Token Budget
+Shows why fixed retrieval budgets scale better than replaying full history.
+
+---
+
+## Quick demo prompts (copy/paste)
+1) Store facts:
+- `Store these exactly: Dog=Nova, City=Manchester, Drink=Pepsi Max.`
+
+2) Recall:
+- `What is my dog's name?`
+- `What city did I say?`
+
+3) Override:
+- `My drink is Coke Zero now. This overrides earlier.`
+- `What is my favourite drink?`
+
+4) Search:
+- `Search for: Nova`
+- `Search for: Manchester`
+
+Then:
+- Download the receipt JSON
+- Upload it into **Verify Receipt**
+- Edit one character inside the receipt and verify again (it should fail)
+
+That pass/fail behaviour is the point.
+
+---
+
+## API Playground examples
+### memory.write
+```json
+{
+  "role": "user",
+  "text": "Store this: Dog=Nova, City=Manchester."
+}
+memory.search
+json
+Copy code
+{
+  "query": "Nova",
+  "k": 8
+}
+receipt.verify
+Paste the full receipt JSON under:
+
+json
+Copy code
+{
+  "receipt": { ... }
+}
+audit.export
+json
+Copy code
+{}
+Persistence
+By default the store uses:
+
+var/rftmem (relative path)
+
+You can set a base directory with:
+
+RFT_MEM_BASE=/your/persistent/path
+
+On hosted environments, persistent storage is what turns this into genuine “restart continuity”.
+
+Run locally
+bash
+Copy code
+pip install -U gradio
+python app.py
+Then open the printed local URL.
+
+Why this matters
+If you’re building agents for real users, you need more than “it usually works”:
+
+Debuggability: show exactly what influenced a decision.
+
+Safety: block actions unless evidence verifies.
+
+Compliance readiness: export a bundle you can actually defend.
+
+Cost control: retrieve a fixed budget instead of replaying history forever.
+
+TrustStack is a working demo of that philosophy: memory you can audit, not memory you’re told to believe.
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference