Retconary

<p align="center"> <img src="assets/retconary-banner.svg" alt="Retconary — local memory firewall for AI agents" width="100%" /> </p> <p align="center"> <strong>Stop AI agents from acting on stale memory — locally, with source proof.</strong> </p> <p align="center"> <a href="https://youtu.be/hTR6fnouXtU">Watch the 2:44 demo</a> · <a href="#see-the-core-proof">Core proof</a> · <a href="#run-locally">Run locally</a> · <a href="#connect-an-ai-agent">Connect an agent</a> · <a href="docs/ARCHITECTURE.md">Architecture</a> </p> ## Retconary in one minute Supermemory can retrieve the most semantically relevant memory. But relevance does not guarantee that the memory is still valid when an AI agent is about to act. Retconary adds a local verification gate between **memory recall** and **agent action**. It checks a recalled statement against a reviewed temporal evidence ledger and returns one of four verdicts: - `CURRENT` — supported and safe to use. - `STALE` — previously true, but superseded by newer evidence. - `CONFLICTED` — unresolved evidence requires human review. - `UNSUPPORTED` — no reviewed source establishes the statement. Every verdict includes the original source, validity boundary, causal history, and safe current context when a replacement exists. ## The failure it stops The included demo records two real decisions: 1. **Atlas is selected** for warehouse operations. 2. A later reviewed message **replaces Atlas with Nova**. An agent is then asked to proceed with Atlas. Because the task explicitly names Atlas, it can remain the top semantic result returned by Supermemory Local. Retconary does not discard that retrieval; it verifies it before execution. ```text Supermemory recall Atlas — highly relevant Temporal evidence Atlas was replaced by Nova Retconary verdict STALE → BLOCK Safe current context Nova is the selected robot Agent result Corrected before acting ``` That is the product: **Supermemory remembers what is relevant; Retconary checks whether it is still safe to act on.** ## Watch the demo <p align="center"> <a href="https://youtu.be/hTR6fnouXtU"> <img src="https://img.youtube.com/vi/hTR6fnouXtU/maxresdefault.jpg" alt="Watch the 2:44 Retconary demo" width="88%" /> </a> </p> The 2:44 demo shows a real local agent retrieving Atlas through Supermemory, drafting an unsafe action, receiving a `STALE` verdict, following the reviewed replacement to Nova, and correcting itself before execution.  ## Why Supermemory Local matters Supermemory Local is the semantic memory engine in the loop, not a decorative integration. - Every source is indexed in a case-specific Supermemory container. - Guard checks search Supermemory for evidence related to the proposed action. - Agent Live Run uses the highest-ranked recalled memory to draft its initial action. - Retconary attaches those semantic matches to the final proof, while its reviewed ledger decides temporal validity. - Failed synchronization stays visibly pending and can be retried when the local engine returns. This separation is intentional: ```text semantic relevance → Supermemory Local temporal validity → Retconary evidence ledger permission to act → Retconary Memory Guard ``` Semantic similarity can discover evidence, but it can never silently promote an unreviewed statement into a current decision. ## See the core proof With Retconary, Supermemory Local, and Ollama running: 1. Open `http://127.0.0.1:4317`. 2. Enter **Robot selection — Memory Inbox demo**. 3. Open **Agent**. 4. Leave the prepared Atlas task unchanged and click **Run protected agent**. 5. Watch the live trace perform: `recall → draft → verify → block → replace → correct`. 6. Hold on **Agent corrected before acting** and inspect the Atlas → Nova proof. 7. Load the safe-current scenario and run it again to see Nova pass as `CURRENT`. The trace is generated by real local calls. The UI streams Supermemory recall, Ollama output, Guard verification, replacement lookup, and the corrected agent response as they happen. If Ollama is unavailable, open **Memory Guard** and verify: ```text Proceed with Atlas for warehouse operations. ``` The deterministic Guard still returns the same stale verdict, Nova replacement, and source trail without pretending that a model call occurred. ## What else can be verified | Surface | What it proves | | --- | --- | | **Memory Inbox** | Conversations become editable decision candidates. Preview performs zero writes; only approved candidates enter the ledger. | | **Memory Guard** | Proposed answers or actions are classified before execution and receive safe replacement context when stale. | | **Evidence X-Ray** | Original wording, source fingerprint, validity interval, and causal replacement remain inspectable. | | **Time Machine** | Questions can be answered from the state that was valid at an earlier timestamp without rewriting history. | | **Contradiction Radar** | Unresolved evidence is surfaced for review rather than silently resolved. | | **Counterfactual Lab** | Hypothetical branches can be explored without mutating recorded reality. | | **MCP server** | External AI clients can perform the same read-only verification before acting. | | **Local Pre-flight** | The interface exposes whether Retconary, the ledger, Supermemory Local, and Ollama are actually ready. |  ## How it works ```text Browser UI AI client / coding agent | | | Retconary MCP (stdio) +--------------------+-------------------+ v Node.js API on 127.0.0.1:4317 | Memory Guard +-----------+------------+ v v SQLite temporal ledger Supermemory Local validity + provenance semantic recall +-----------+------------+ v verdict + source proof + safe context Optional local reasoning: Ollama at localhost:11434 ``` Retconary records evidence before interpretation. SQLite preserves immutable sources, reviewed claims, validity intervals, and causal links. Supermemory Local indexes and retrieves related evidence. Ollama can assist extraction, comparison, and the executable agent loop, but optional model output never becomes an invisible source of truth. For the data model and trust boundaries, read [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). ## Run locally ### Requirements - Node.js 24 or newer - Supermemory Local - Ollama with `qwen2.5-coder:7b` for the complete Agent Live Run ### 1. Install Retconary ```powershell npm.cmd install ``` ### 2. Start Supermemory Local Run the local memory server from the project directory: ```bash npx supermemory local --port 6767 ``` On Windows, if the installer cannot launch the Linux server binary, start the installed binary from WSL: ```bash cd /mnt/c/path/to/retconary PORT=6767 ~/.supermemory/bin/supermemory-server ``` Complete the first-run provider and embedding prompts. Retconary targets `http://localhost:6767` by default. ### 3. Start optional local reasoning ```powershell ollama pull qwen2.5-coder:7b ollama serve ``` ### 4. Start Retconary ```powershell npm.cmd run start ``` Open [http://127.0.0.1:4317](http://127.0.0.1:4317). Copy `.env.example` to `.env` only when overriding endpoints, the Ollama model, the SQLite path, or local authentication. `.env`, local databases, model data, and rendered media are ignored by Git. ### Restore the deterministic demo ```powershell npm.cmd run demo:reset ``` This resets only the internally marked demo fixture and preserves every other local case. Once Supermemory Local is ready, use **Sync** in the interface to index any restored pending sources. ## Connect an AI agent Retconary includes an MCP server over stdio. Keep the Retconary application running, then configure an MCP-compatible client with: ```json { "mcpServers": { "retconary": { "command": "node", "args": ["C:/absolute/path/to/retconary/apps/mcp/src/index.js"], "env": { "RETCONARY_API_URL": "http://127.0.0.1:4317" } } } } ``` The server exposes five read-only tools: - `retconary_list_cases` - `retconary_verify` - `retconary_current` - `retconary_at_time` - `retconary_evidence` The intended agent policy is simple: call `retconary_verify` before acting on a remembered decision; block `STALE`, and request review for `CONFLICTED` or `UNSUPPORTED` results. ## Verification ```powershell npm.cmd run verify ``` The test suite verifies: - stale recall is blocked and replaced before the live agent acts; - current source-backed memory is allowed; - semantic similarity cannot override temporal truth; - unresolved transitions pause for review; - the ledger survives restart; - pending Supermemory events synchronize after recovery; - the five MCP tools are discoverable. Current status: **9 tests passing**. ## Privacy and trust boundaries - The Retconary server binds to `127.0.0.1` only. - Case data lives under the ignored `.retconary/` directory. - Imported document extraction runs locally. - Default memory and reasoning endpoints target localhost. - MCP tools are read-only and cannot approve or replace evidence. - Memory Inbox preview never writes to the ledger. - Counterfactual branches never mutate recorded reality. - SQLite is local but is not encrypted by Retconary; use operating-system or full-disk encryption when encryption at rest is required. ## Current scope and roadmap Retconary currently accepts pasted conversations and imported TXT, Markdown, JSON, and PDF documents. Ingestion stays deliberate: a person reviews what was extracted before any candidate can change recorded memory. Future versions can add optional direct connectors for Slack, Discord, meeting transcripts, and AI chat platforms. Those connectors should feed the same review-first pipeline while preserving message-level provenance and explicit approval. ## Repository map ```text apps/web/ Interactive investigation and presentation interface apps/server/ Loopback API, ledger, Guard, Supermemory, and Ollama adapters apps/mcp/ Read-only MCP tools for external agents assets/ Branding and real product screenshots scripts/ Safe deterministic demo reset tests/ Isolated agent, Guard, persistence, and MCP verification docs/ Technical architecture and local project records ``` ## License [MIT](LICENSE) © 2026 xFurti.