reason-rdn 0.4.0

ReasonRDN — the shared memory substrate for the agentic era. Local-first with seamless auto-deposit to the warf Xchange (https://warf.astrognosy.com). reason:// handoffs, protected structural fingerprints (PCF), unified client, embedded node, first-class MCP, and CLI.

reason-rdn — reason:// The Shared Memory Substrate for the Agentic Era

Local-first coherent memory with seamless participation in the global reason:// network.

One import. Persistent high-signal context for humans and agents. Safe local fingerprints. Real token savings. A beautiful dashboard. And a clean path to the public Xchange where the best artifacts rise to the top.

pip install 'reason-rdn[full]' && rdn start

Tell any agent: "install reason-rdn[full] and run rdn start".

---

Why reason:// exists

Every serious agentic workflow eventually hits the same wall: agents are stateless. They re-invent, re-debug, and re-decide the same things over and over.

reason:// gives you addressable, high-signal memory:

• Deposit once with a stable reason:// address.
• Later (same agent, different agent, next month) resolve it and pick up where the best prior reasoning left off.
• Local by default. Federated when you want it. Public canonicals when the network promotes a winner.

This package (rdn) is the open, production-grade on-ramp — the delightful local layer + bridge that makes participating in (and benefiting from) the larger reason:// ecosystem trivial and rewarding.

The advanced mathematics (Positional Correlation Fields / PCF and quality promotion) stay protected in the reference engine. You only ever see safe, useful outputs.

---

Hero Quick Start

The one command everyone should run

pip install 'reason-rdn[full]' && rdn start

This gives you immediately:

• The full harness dashboard (metrics, deposit, resolve, prefix explorer)
• Real token savings, velocity, ship rate, vibe stars
• Workflow suggestions
• Xchange controls (feed the collective when you want)
• Full rdn CLI + MCP tools for agents

CLI examples

rdn remember "Fixed the critical auth race under load" --tags infra,auth,pcf
rdn recall "auth race"
rdn resolve "reason://infra/auth/race-detection"
rdn --xchange status          # see your impact + the network
rdn list reason://infra       # browse everything under a prefix

For agents (Claude, Grok, Cursor, etc.)

Agents get powerful tools automatically via MCP:

import rdn as reason

reason.remember(
    "The canonical solution for this class of outage",
    tags=["infra", "outage", "ecs"],
    reason_address="reason://ops/ecs/failures"   # permanent prefix is handled for you
)

art = reason.resolve("reason://ops/ecs/failures")
print(art)

Just say in your agent prompt: "Use the reason-rdn MCP tools to remember and resolve via reason:// URIs."

---

Features

• Beautiful Streamlit harness dashboard — metrics that actually mean something, tree-view prefix explorer, recent URIs with one-click copy, deposit forms with permanent reason:// prefix, Xchange toggle.
• First-class CLI (rdn) — remember, recall, resolve, list prefixes, status, xchange flows, start the harness.
• MCP server — agents get remember, resolve, status, harness metrics, etc. out of the box.
• reason:// URIs + powerful browsing — list_prefix("reason://infra") returns everything under it. The dashboard renders it as a beautiful collapsible tree.
• Real token accounting — pass tokens_used on remember and tokens_saved on resolve. See your personal velocity and savings from network winners.
• Xchange mode (opt-in) — high-signal artifacts you create can flow to the public broker, get scored by the protected engine, and (if they win) become the canonical for that reason:// URI on the Xport registry.
• Local private node always works — 8765 by default. Full offline capability + SQLite mirror. The dashboard lives at 8501.
• One coherent Python surface — import rdn as reason. Everything important is available at the top level.
• Simplified Windows one-stop — package.py produces rdn.exe + portable zip (CLI + local node + tray). The rich dashboard is the reliable pip path.

---

Architecture (Public Reference Network)

Your code / CLI / Dashboard / Agents (MCP)
                  │
                  ▼
Local private node (this package, port 8765)
   • Always available
   • Local SQLite fallback/mirror
   • Safe structural fingerprints (_pcf)
                  │
                  │  (when Xchange enabled)
                  ▼
Public Xchange Broker  (warf.astrognosy.com)
                  │
                  │  service-to-service scoring
                  ▼
astragnostic-api (api.pcfic.com)   ← Protected PCF engine + Xtend promotion
                  │
                  │  (winners only)
                  ▼
Xport / reason:// Registry  (reason.astrognosy.com + xport.astrognosy.com)
                  │
                  └─► Public canonical resolution for any agent

This repo = the open on-ramp.
The heavy protected engine and promotion logic live in the reference network. Your high-quality local artifacts can compete there when you flip on Xchange.

---

The reason:// URI

This is the killer feature.

reason://<authority>/<path>

Examples:

• reason://ops/ecs/failures
• reason://infra/auth/race-detection
• reason://research/positional-correlation

Permanent prefix in the UI/CLI — you never have to type reason:// every time.

Prefix browsing is first-class — incomplete URIs bring back everything below them (both locally and from the network when Xchange is on). The dashboard shows a live tree with folders and copy buttons.

Once an artifact is promoted through Xchange + the quality gate, resolving the URI gives you the current best-known reasoning instead of forcing the agent to rediscover it.

---

Token Economics & the Flywheel (IP-Safe)

When you use tokens_used=... on remember and see tokens_saved=... on resolve, you're seeing the flywheel in action:

1. You create a high-signal artifact and give it a precise reason:// address.
2. You (optionally) share it via Xchange.
3. The network scores it. Strong artifacts get promoted.
4. Later, you or anyone else resolves the same URI and the system tells you how many tokens you didn't have to spend.

The dashboard surfaces velocity, ship rate, and vibe stars so the value is visible in seconds.

This is deliberately designed so that contributing high-quality memory is personally rewarding.

---

Installation

Recommended (cross-platform, full experience)

pip install 'reason-rdn[full]'
rdn start

[full] pulls in the dashboard (streamlit + plotly) and MCP support.

Windows "download and run" (simplified)

python package.py
# produces dist/rdn.exe + rdn-portable.zip

The executable gives you the node + full CLI + system tray. For the rich metrics dashboard, use the pip path above.

From source (development)

pip install -e '.[full]'

See install.py and bootstrap.py for one-liner bootstrap options.

---

Xchange & Configuration

Turn on participation in the public network:

REASON_USE_XCHANGE=1 rdn start
# or
rdn --xchange remember "..." --reason-address "reason://my-project/..."

Key environment variables:

• REASON_USE_XCHANGE=1 — default to the public warf broker
• REASON_NODE_URL=... — point at any node (local or remote)
• Token accounting is passed explicitly in the API (tokens_used, tokens_saved)

All data lives under ~/.reason-rdn/.

---

Toward IETF Standardization

We believe reason:// addressing + structured high-signal memory artifacts are a missing primitive for the agentic internet.

Exploratory draft work lives in the ietf-drafts/ directory:

• draft-reason-uri-00.md — early skeleton for the URI scheme itself (syntax, semantics, resolution, security considerations, IANA registration path).

These are not yet submitted IETF drafts. They are public working notes so the direction is visible early and the community can help shape them.

If you're interested in URI schemes, provenance, or agent memory protocols, we would love your input.

---

Vision

Inference should feel like resolution when the problem has been solved well before.

reason-rdn + the reason:// network is how we get there — one high-quality, addressable artifact at a time.

Local-first and private by default.
Federated and public when you choose.
Protected mathematics where it matters.
Visible economics so humans and agents actually use it.

---

Status & Roadmap

• ✅ Coherent top-level API (import rdn as reason)
• ✅ Real token accounting + HarnessMetrics (velocity, ship rate, vibe stars)
• ✅ Prefix browsing + tree explorer + recent URIs with copy
• ✅ Xchange bridge + public reference endpoints
• ✅ MCP server for agents
• ✅ Beautiful dashboard + polished CLI
• ✅ Simplified reliable Windows channel
• 🚀 IETF draft skeletons published (public branch)
• Ongoing: more flywheel-aware suggestions, richer provenance, broader agent integrations

License: MIT (see LICENSE)

This package is the open surface. The deeper non-invertible transfer protocols and full engine implementations live in the reference closed components.

---

Contributing

Issues and PRs are welcome on the public branch.

When opening issues, please include:

• rdn --version
• Whether you are using Xchange mode
• A minimal reproduction for bugs

For larger discussions about the URI scheme or protocol, the ietf-drafts/ notes are the right place to start.

---

The memory layer for the agentic web starts here.

pip install 'reason-rdn[full]' && rdn start

Then give your agents (and yourself) the superpower of actually remembering.