Noodl Cognitive Runtime

Python Cognitive Runtime for Noodl — built from scratch around Goal + memory + producers.

Sibling	Role
noodl	Product shell (Next.js) — Goal UX, BFF, Postgres SoR
this repo	Cognitive engine
graph-of-thought	Extraction / structured reasoning

Goal → Planner → Memory → Scheduler → Context → Agents → Execution → Evaluation → Learning

Docs

Doc	Purpose
AGENTS.md	Constitution for humans + agents
docs/VISION.md	Engine thesis
docs/ROADMAP.md	R0–R8 + waves α–ε (canonical)
docs/rfc/0001-…	Wave α RFC (Draft)
docs/adr/0001-…	GraphStore port ADR (Proposed)

Current focus: Wave α (R0–R1)

Phase	Status	What
R0 Contracts	in progress	Pydantic models in noodl-core
R1 Graph Runtime	in progress	add/link/query/reason + events + GraphStore port

Later packages (planner … evaluation) exist as thin stubs — do not treat them as Done.

Packages

Package	Role
noodl-core	Contracts (Goal, Task, Event, ontology)
noodl-knowledge	Graph runtime + persistence port
noodl-tracing	Event bus / timeline
others	Scaffold for R2+ — keep thin until their phase

Quick start

Python ≥ 3.12 · uv

cd noodl-runtime
uv sync
uv run pytest
uv run python examples/goal_loop_demo.py

Full loop (Goal → … → projection)

from noodl_workflow import CognitiveRuntime

result = CognitiveRuntime().run("Build Connor Runtime")
print(result.projection)  # step 8 — what a Dashboard would render

Graph only (R1)

from noodl_core import ObjectKind, RelationKind
from noodl_knowledge import Graph
from noodl_tracing import EventBus

events = EventBus()
graph = Graph(events=events)

scheduler = graph.add(ObjectKind.CONCEPT, "Scheduler")
temporal = graph.add(ObjectKind.TECHNOLOGY, "Temporal")
graph.link(scheduler.id, temporal.id, RelationKind.RELATED_TO)

print(graph.reason(scheduler.id))
print([e.type for e in events.timeline()])

Non-goals (now)

• LangGraph / CrewAI as system of record
• Neo4j as SoR (adapter later)
• Nesting this repo inside noodl/
• Multi-agent fleets before R1 is solid

Principles

1. Agents produce cognitive objects, not free-form chat as truth
2. Context packs are ranked subsets — never dump full memory
3. Postgres product SoR stays behind the TypeScript BFF
4. Build order: R0 → R1 → R2 → … (see ROADMAP)