From 5bd80ffcfefe68d4dfe142ef28a1116651af5602 Mon Sep 17 00:00:00 2001 From: Agent Zero Date: Sat, 4 Apr 2026 12:36:38 +0000 Subject: [PATCH] docs: add Truth Engine documentation (#41) --- README.md | 233 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) diff --git a/README.md b/README.md index a472519..882a91e 100644 --- a/README.md +++ b/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