ReasonState

Governed, deterministic memory for AI agents: summaries-only context, partial recompute, temporal rollback, and replay - no prompt hacking, <10 LOC to use.”

Comment

About the Project

What it is

ReasonState is a governed, deterministic memory layer for AI agents. It gives you summaries-only context, partial recompute for new facts, temporal rollback for tool conflicts, and replay/time-travel - all in <10 LOC with a default helper (planAndAct).

Inspiration

Agents today often:

  • Hallucinate structure
  • Lose working memory
  • Burn tokens on repeats
  • Fail silently on tool conflicts
  • Can’t be replayed or audited

I wanted a JSON-first, governance-first approach that any Node/Next developer can drop in without writing orchestration graphs or prompt hacking. I built this for the Jarvis Track at the 2025 xAI Hackathon.

How I built it

  • Core engine: JSON state with raw vs summary nodes, append-only patch DSL (add/replace), lineage, timestamps, edges (depends_on, contradicts, temporal).
  • Governance: Dirty/unknown gating, dependency/temporal blocking, contradiction detection, rollback helpers.
  • Context: Summaries-only, deterministic ordering, prioritizing dirty/new/assumptions; no raw details to the model.
  • LLM integration: Grok 4.1 with a strict system prompt, validation/backoff for patches, and engine-assigned IDs.
  • Replay: NDJSON log + checkpoints; deterministic rebuild to prove what the agent knew and when.
  • Default DX: planAndAct helper + minimal facade (addNode, updateNode, recompute, rollback); agent-note fallback for coherence; example tools in examples/.

What I learned

  • Governance and determinism beat prompt tweaking for reliability.
  • Summaries-only context with strict validation keeps models from drifting and reduce token consumption when compared context window dump + summary truncation methods.
  • Replay/time-travel is a superpower for debugging and audit, not just a demo trick.
  • A tiny default helper eliminates most DX friction.

Challenges

  • Enforcing strict patch rules (no deletes, no raw writes from LLM) while keeping UX simple.
  • Balancing semantic recompute (new facts) vs temporal rollback (tool clashes) in a single UX.
  • Making replay deterministic across runs and surfacing it clearly in the demo.
  • Keeping the package lean (core only) while providing useful examples.

Why it matters

Developers get governed agent memory, partial recompute, and deterministic replay without building their own graphs or prompts. It’s fast to adopt, hard to break, and easy to audit.

Built With

Share this project:

Updates