nodemind

A unified self-modifying graph substrate for AI agents.

Status: pre-alpha. The design is locked (docs/design.md), Week-1 verification experiments both passed (experiments/), and the v0.1 implementation is in progress.

The idea

Today, agent memory lives in a vector DB, agent tools live in a function registry, agent schedules live in a crontab, and sub-agents live in some orchestrator. Four stacks, four mental models, four sets of API calls. The split is a legacy of pre-agent infrastructure. For an agent, memory chunks, tools, scheduled triggers, and child agents are all the same thing: addressable references in its environment that it can read, mutate, link, or create.

nodemind treats all four as type-tagged nodes in one graph the agent itself reshapes. Five node types (Memory, Tool, Cron, Agent, Task) and five edge types (triggers, uses, remembers, spawned_by, derives_from), persisted in RyuGraph (the active fork of Kuzu that took over after kuzudb/kuzu was archived in October 2025), visualized by an event-log replay viewer that lets you scrub through the agent's graph evolution as a time-lapse.

v0.1 scope

The first release ships a research-agent demo: given a task ("summarize ML interpretability since 2024"), the agent grows its own tools, fires a self-scheduled reflective cron, spawns a sub-agent for one paper deep-dive, and the viewer replays the resulting graph evolution as a 60–90 second clip. Full scope in docs/design.md.

Install

pip install nodemind   # not yet on PyPI; coming with v0.1

For local development against this repo:

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

Try the viewer

Generate a sample event log and open the time-lapse viewer in your browser:

make view-demo
# or, equivalently:
python -m nodemind.viewer --sample ./demo-run

This produces demo-run/graph_events.jsonl (37 events covering all five node types and all five edge types) and renders a self-contained demo-run/index.html. Drag the scrub bar to replay the substrate's growth; click any node to inspect its payload.

The viewer is a single HTML file with the events embedded inline (only D3 is loaded from a CDN), so it works from file:// without a server. To visualize a real agent run, pass its workdir instead:

python -m nodemind.viewer ./run-1

License

Apache-2.0. See LICENSE.