OrKa isn’t a framework. It’s an instrument panel for artificial cognition.
If you’ve ever tried to debug an LLM pipeline and thought, „Why the hell did it do that?“, you’re not alone. Most systems built today chain prompts or run black-box workflows. They don’t see their own reasoning. And worse: we can’t see it either.
This is the story of how we built a TUI (Terminal UI) inside OrKa that makes cognition observable. Not just logs. Not just traces. Actual live visual feedback from the AI’s memory and decision points. You’re not guessing anymore. You’re watching the mind unfold.
And it’s all happening in your terminal.
🎩 OrKa in 10 Seconds
OrKa (Orchestrator Kit for Agents) is a YAML-defined orchestration layer for modular AI cognition. You define agents, their types (binary, classifier, router, builder…), their prompts, and their connection logic. Then OrKa runs the graph, manages memory, and logs every step.
The TUI is where it gets personal. It’s not a dashboard. It’s a mindspace.
🕹️ Why Build a TUI in 2025?
We didn’t want another Grafana. OrKa is about local, deterministic cognition. Real-time. Reproducible. Human-auditable. The TUI is the interface between execution and explanation.
We needed:
- A way to see memory at every timestep
- A view of what agent is executing and why
- A timeline of forks, joins, routers, and overrides
- A way to debug failures by watching cognitive flow, not parsing logs
The result is the OrKa TUI: a ncurses-powered, zero-mouse, full-observable cognitive HUD.
🔮 Anatomy of the Observable TUI
Let’s walk through the five major screens that make OrKa’s memory truly observable.
1. Dashboard: Memory System Overview
This is your entry point. It gives a quick-glance read on the state of all memory zones, system health, recent logs, and backend stats. You’ll see real-time updates on:
- Short- and long-term memory stats
- Connection status and backend info
- Cached memory hit rate and trends
Think of it like a cockpit for cognition.
2. Short-Term Memory
This screen filters all memory entries with TTL < 1 hour. Use it to:
- Inspect recent cognitive states
- See which agents wrote what and when
- Observe expiration timing in live countdown
All updates auto-refresh every 2 seconds.
3. Long-Term Memory
This view focuses on stable, persistent entries. If a memory outlives an hour or is flagged to persist, it appears here.
You can filter by content type and export persistent memory sets for audit and reasoning analysis.
4. Memory Logs (Full System Activity)
This is your forensic zone. Every memory write, orchestration log, and agent call appears here with timestamp, TTL, confidence, and preview.
You’ll use this when debugging:
- Why a router picked a certain branch
- What fork paths were launched
- What memory was shared downstream
5. Memory Health Panel
A deep, live diagnostic screen:
- Memory performance (latency, cache hit, response time)
- System health status
- Connection integrity
- Historical memory trends
This lets you spot decay, performance dips, or unexpected eviction early.
📈 How It Works Under the Hood
The TUI is built using Python npyscreen, backed by Redis Streams.
Every event in the OrKa runtime emits a structured log into Redis:
{
"ts": 17284612,
"agent_id": "router_1",
"type": "router",
"input": "...",
"confidence_scores": { "factual": 0.87, "joke": 0.13 },
"picked": "factual"
}
The TUI subscribes to a Redis consumer group and renders incoming events into their corresponding panels. All logic is reactive. No polling.
Forks and joins are built from a virtual execution tree updated on each event.
Memory writes go into their own stream, decoded per scope.
🧠 Why It Matters
Observability in AI is not a luxury. It’s foundational. If you can’t see why something happened, you can’t trust it.
And in OrKa, trust is a function of:
- Traceability: every agent call, every fork, every branch is visible.
- Memory introspection: see what the AI knows and what it forgets
- Router transparency: no more guesswork on why a decision was made
Most frameworks give you logs.
OrKa gives you cognition.
📊 What’s Next
The TUI is getting scoped memory write filters (toggle per layer), router override mode, and dark mode (just kidding, it’s all black already).
But more deeply: this is just the beginning of building a transparent cognition debugger.
We’re working on:
- Live diff views between agent outputs
- Path prediction overlays (what would have run if scores were different)
- Interactive rollbacks
And beyond TUI? A WebGL-based 3D cognition flow visualizer.
But for now, it’s all happening in the terminal. And it’s glorious.
If you’re building agent workflows and can’t explain why your LLM did what it did, you need OrKa.
Or better: fork it, run it, and watch cognition come alive in your terminal.
Want to see the TUI in action? Drop a comment and we’ll stream a live demo.