docs: add Truth Engine documentation (#41)

README.md

@@ -13,6 +13,7 @@ OpenBrain is a Model Context Protocol (MCP) server that provides AI agents with
 - 🔐 **Shared Memory by Token**: Agents using the same API token share memory visibility while retaining source-agent provenance
 - ♻️ **Deduplicated Ingest**: Near-duplicate facts are merged instead of stored repeatedly
 - ⚡ **High Performance**: Rust implementation with async I/O
+- 🔍 **Truth Engine**: Optional neuro-symbolic truth scoring using PLN deduction and ECAN attention economics (based on Bushidai Truth Simulator by TS87)
 
 ## MCP Tools
 
@@ -22,6 +23,8 @@ OpenBrain is a Model Context Protocol (MCP) server that provides AI agents with
 | `batch_store` | Store 1-50 memories atomically in a single call with the same deduplication rules |
 | `query` | Search memories by semantic similarity, optionally filtering by source agent |
 | `purge` | Delete memories visible to the current API token, optionally filtering by source agent or time range |
+| `evaluate` | On-demand truth scoring of a claim using neuro-symbolic reasoning (requires Truth Engine) |
+| `truth_status` | Get Truth Engine scoring statistics and coverage metrics (requires Truth Engine) |
 
 ## Quick Start
 
@@ -403,6 +406,236 @@ clients use the same API token, they already share memory visibility.
 | `OPENBRAIN__EMBEDDING__MODEL_PATH` | `models/all-MiniLM-L6-v2` | ONNX model path |
 | `OPENBRAIN__AUTH__ENABLED` | `false` | Enable API key auth |
 
+## Truth Engine
+
+### Overview
+
+The Truth Engine is an integrated neuro-symbolic reasoning system that continuously scores stored memories for truthfulness and reliability. Based on the **Bushidai Truth Simulator** by Thijs Smits (TS87), it runs as a background worker within the OpenBrain process, evaluating memories against each other using cross-referencing, deductive logic, and attention economics.
+
+Core components:
+
+- **PLN (Probabilistic Logic Networks)**: Deductive reasoning engine that evaluates logical consistency between memories, computing truth values and confidence scores based on evidence overlap and inferential strength.
+- **ECAN (Economic Attention Network)**: Attention economy module that manages importance and relevance of memories over time, applying decay rates and spreading activation to maintain a dynamic salience map.
+- **Cross-Reference Engine**: Finds semantically related memories using vector similarity and evaluates corroboration or contradiction patterns across the memory corpus.
+
+The Truth Engine is entirely optional and disabled by default. When enabled, it enriches every stored memory with truth metadata without affecting query latency.
+
+### Truth Engine Configuration
+
+All Truth Engine settings use the `OPENBRAIN__TRUTH__*` environment variable prefix:
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `OPENBRAIN__TRUTH__ENABLED` | bool | `false` | Enable or disable the Truth Engine background worker and tools |
+| `OPENBRAIN__TRUTH__SCORING_INTERVAL_SECONDS` | u64 | `300` | How often (in seconds) the background worker runs a scoring cycle |
+| `OPENBRAIN__TRUTH__BATCH_SIZE` | usize | `50` | Maximum number of unscored memories to process per cycle |
+| `OPENBRAIN__TRUTH__RESCORE_AFTER_SECONDS` | u64 | `86400` | Re-score memories older than this threshold (seconds) to keep truth values current |
+| `OPENBRAIN__TRUTH__PLN_BASE_CONFIDENCE` | f32 | `0.85` | Base confidence for PLN deductive reasoning when no prior evidence exists |
+| `OPENBRAIN__TRUTH__ECAN_DECAY_RATE` | f32 | `0.95` | ECAN attention decay rate per scoring cycle (closer to 1.0 = slower decay) |
+| `OPENBRAIN__TRUTH__ECAN_SPREAD_FACTOR` | f32 | `0.3` | How much attention spreads to semantically related memories (0.0–1.0) |
+| `OPENBRAIN__TRUTH__CONTRADICTION_THRESHOLD` | f32 | `0.85` | Similarity threshold above which conflicting memories are flagged as contradictions |
+| `OPENBRAIN__TRUTH__VERIFICATION_THRESHOLD` | f32 | `0.7` | Minimum corroboration score required to classify a memory as "verified" |
+| `OPENBRAIN__TRUTH__CROSS_REF_LIMIT` | usize | `10` | Maximum number of related memories to cross-reference per scored memory |
+
+### New MCP Tools
+
+#### `evaluate`
+
+On-demand truth scoring of a claim. Use this to evaluate a specific statement against the existing memory corpus without waiting for the background worker cycle.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `claim` | string | Yes | The claim or statement to evaluate for truthfulness |
+| `context` | string | No | Optional additional context to inform the evaluation |
+
+**Returns:**
+
+```json
+{
+  "truth_value": 0.82,
+  "truth_confidence": 0.91,
+  "truth_category": "verified",
+  "reasoning": [
+    "Found 4 corroborating memories with high semantic similarity",
+    "PLN deduction yielded truth value 0.82 with confidence 0.91",
+    "No contradicting memories detected"
+  ]
+}
+```
+
+**Example MCP call:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "evaluate",
+    "arguments": {
+      "claim": "The deployment uses JWT with refresh tokens for authentication",
+      "context": "HetLife API project"
+    }
+  }
+}
+```
+
+#### `truth_status`
+
+Get current Truth Engine scoring statistics and coverage metrics. Takes no parameters.
+
+**Returns:**
+
+```json
+{
+  "enabled": true,
+  "total_memories": 1250,
+  "scored_memories": 1100,
+  "unscored_memories": 150,
+  "coverage": 0.88,
+  "categories": {
+    "verified": 420,
+    "plausible": 510,
+    "unverified": 150,
+    "contradicted": 20
+  },
+  "scoring_config": {
+    "interval_seconds": 300,
+    "batch_size": 50,
+    "rescore_after_seconds": 86400
+  }
+}
+```
+
+**Example MCP call:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/call",
+  "params": {
+    "name": "truth_status",
+    "arguments": {}
+  }
+}
+```
+
+### Enhanced Query Results
+
+When the Truth Engine is enabled, `query` results include additional truth metadata fields on each returned memory:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `truth_value` | f32 \| null | Computed truth value (0.0–1.0), where 1.0 indicates highest truthfulness |
+| `truth_confidence` | f32 \| null | Confidence in the truth value (0.0–1.0), reflecting the quality and quantity of evidence |
+| `truth_category` | string \| null | Classification: `verified`, `plausible`, `unverified`, or `contradicted` |
+
+These fields are `null` for memories that have not yet been scored by the background worker. Query performance is not affected — truth fields are read from pre-computed columns, not calculated at query time.
+
+**Example query response with truth fields:**
+
+```json
+{
+  "content": "The API uses PostgreSQL 16 with pgvector extension",
+  "similarity": 0.89,
+  "truth_value": 0.94,
+  "truth_confidence": 0.87,
+  "truth_category": "verified",
+  "metadata": { "source_agent": "ingwaz-a0", "project": "openbrain" }
+}
+```
+
+### How It Works
+
+The Truth Engine operates as a non-blocking background worker loop:
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                  Truth Engine Worker Loop                     │
+│                                                              │
+│  1. Fetch unscored/stale memories (batch_size per cycle)     │
+│           │                                                  │
+│  2. Cross-reference: find related memories via vector         │
+│     similarity (up to cross_ref_limit per memory)            │
+│           │                                                  │
+│  3. PLN Score: deductive reasoning over evidence              │
+│     → truth_value + truth_confidence                         │
+│           │                                                  │
+│  4. ECAN Update: adjust attention/importance weights          │
+│     → spread activation to related memories                  │
+│           │                                                  │
+│  5. Categorize: assign truth_category based on thresholds    │
+│           │                                                  │
+│  6. Write back: batch update truth scores to database         │
+│           │                                                  │
+│  7. Sleep for scoring_interval_seconds                        │
+└──────────────────────────────────────────────────────────────┘
+```
+
+**Truth Categories:**
+
+| Category | Description |
+|----------|-------------|
+| `verified` | Corroborated by multiple related memories above the verification threshold |
+| `plausible` | Some supporting evidence but below the verification threshold |
+| `unverified` | Insufficient related memories to form a judgment |
+| `contradicted` | Conflicts with one or more highly similar memories above the contradiction threshold |
+
+**Key Design Properties:**
+
+- **Non-blocking**: The worker runs in its own async task and never blocks query or store operations
+- **Idempotent**: Re-scoring a memory converges to the same result given the same corpus state
+- **Batch-oriented**: Processes memories in configurable batches to bound resource usage
+- **Self-healing**: Stale scores are automatically refreshed after `rescore_after_seconds`
+- **Graceful startup**: Waits for the embedding engine to be ready before starting the first cycle
+
+### Truth Engine Quick Start
+
+Enable truth scoring with minimal configuration:
+
+```bash
+# Enable truth scoring
+export OPENBRAIN__TRUTH__ENABLED=true
+export OPENBRAIN__TRUTH__SCORING_INTERVAL_SECONDS=300
+export OPENBRAIN__TRUTH__BATCH_SIZE=50
+```
+
+For production tuning, consider adjusting these based on your memory corpus size:
+
+```bash
+# Production tuning example
+export OPENBRAIN__TRUTH__ENABLED=true
+export OPENBRAIN__TRUTH__SCORING_INTERVAL_SECONDS=120   # Score more frequently
+export OPENBRAIN__TRUTH__BATCH_SIZE=100                  # Larger batches
+export OPENBRAIN__TRUTH__RESCORE_AFTER_SECONDS=43200     # Re-score every 12h
+export OPENBRAIN__TRUTH__CROSS_REF_LIMIT=20              # More cross-references
+export OPENBRAIN__TRUTH__VERIFICATION_THRESHOLD=0.75     # Stricter verification
+```
+
+Run the database migration to add truth columns, then start the server:
+
+```bash
+./target/release/openbrain-mcp migrate
+./target/release/openbrain-mcp
+```
+
+Verify the Truth Engine is running:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "truth_status",
+    "arguments": {}
+  }
+}
+```
+
 ## License
 
 MIT