Kogwistar
Graph-native AI substrate for HyperGraphRAG. Knowledge, Workflow orchestration, conversation memory and wisdom are modeled as hypergraphs. Support strong event sourced provenance and replay.
Install / Use
/learn @humblemat810/KogwistarREADME
kogwistar is a graph-native substrate for governed agent execution with memory and execution.
What This Is
- A substrate for storing knowledge, conversations, workflows, and provenance in the same graph-oriented model.
- A runnable harness for executing workflows and replaying history.
- A security- and governance-aware foundation for building agent systems with inspectable history and traceable answers.
What This Is Not
- Not just another GraphRAG demo.
- Not an agent framework with a fixed opinionated loop.
- Not a finished enterprise product.
See docs/positioning.md for the full architectural framing and docs/LEARNING_PATH.md for the learning order.
Real Use Case
This substrate is not only about memory, conversation, or workflow in isolation. It can also sit underneath a security and governance layer for agent systems.
A concrete example is humblemat810/cloistar, which uses Kogwistar as the substrate for an OpenClaw governance semantics layer. That repo shows a real integration shape where the substrate is used for governed tool execution, approval flows, graph-backed receipts, and bridge/runtime semantics rather than only chat memory or workflow authoring.
At a lighter layer, humblemat810/kogwistar-chat shows the same substrate supporting an application-facing chat experience. Taken together, these examples show that Kogwistar can support multiple layers of implementation, from higher-level application surfaces down to deeper governance and security semantics.
Glossary
substrate: the shared graph-oriented foundation for knowledge, conversation, memory, workflow, execution, and provenance.harness: the execution layer that runs workflows on top of the substrate.provenance: the trace back to the source data, steps, or spans behind a node or answer.replay: rebuilding state or views from stored history.projection: turning authoritative history into queryable views or materialized state.authoritative evented path: the event-history-driven path that carries the strongest replay and provenance guarantees.
Example
Run the graph-native artifact demo to see the full loop end to end:
python -m kogwistar.demo.graph_native_artifact_demo
What it does:
- takes raw notes as input
- validates and normalizes them into graph artifacts
- links related artifacts
- commits the result into history
- rebuilds usable views from that history
- explains results with provenance
This is the quickest way to see how execution becomes reusable state in the same graph.
See docs/graph_native_artifact_demo.md for the short design note and docs/positioning.md for the deeper architectural framing.
If you want the closer agent-loop comparison, the older framework_then_agent_demo remains available as a companion example.
Today the repo implements graph memory and query, workflow design/runtime, governance-oriented patterns, provenance and replay-oriented surfaces, CDC/event-oriented patterns, and self-hostable development paths.
This repo is a substrate with reusable building blocks for replayability, provenance tracking, security boundaries, governance semantics, and projection along the authoritative evented path.
Mental Model In Pseudocode
If the terminology feels abstract, read this first. It is the simplest way to understand the design:
input = user message, document, or workflow definition
events = capture(input)
validated = validate(events)
graph = normalize_to_nodes_and_edges(validated)
connected = link_related_graph_artifacts(graph)
commit(connected) # writes authoritative history
projection = rebuild_views_from_history()
answer = retrieve_with_provenance(projection, question)
In plain words:
- execution and governance decisions are recorded as durable history
- durable history is projected into graph state
- graph state can be replayed or repaired later
- provenance links answers back to the source steps and source spans
More Details
For the layer model, guarantees, and comparisons, see docs/positioning.md and docs/LEARNING_PATH.md.
Graph-Native Artifact Pipeline
This is the clearest demo if you want to see how execution, memory, conversation, provenance, and governance-friendly structure are unified in one graph.
Run the full suite with:
python -m kogwistar.demo.graph_native_artifact_demo
Use --summary-only if you want the one-screen proof view instead of the full report.
The demo runs three small scenarios:
- execution becomes memory
- conversation and workflow live in the same graph
- provenance answers “why” from stored execution history
These are not separate features; they come from the same underlying graph model.
The example stages raw notes, validates them, normalizes them into graph artifacts, links related notes, and commits the result into the same graph store that also holds workflow runs, step executions, and conversation turns. That makes the substrate point visible: execution is not just logged, it becomes graph memory; conversation and workflow are linked in one graph; and provenance queries can explain a result from stored history.
See docs/graph_native_artifact_demo.md for the short design note.
If you want the closer agent-loop comparison, the older framework_then_agent_demo remains available as a companion example.
Quickstart
-
As this is a substrate, you can pick anywhere you immediately want to start with e.g. hypergraphrag, runtime, mcp server, conversation primitives, workflow design, or governance-oriented integration. As your needs grow, you can compose more consistently and coherently.
-
Standalone setup then run simple flow in 2 minutes. (no frontend integration): QUICKSTART.md
-
Application-layer example on top of this substrate:
humblemat810/kogwistar-chat -
OpenClaw governance example built on this substrate:
humblemat810/cloistar -
Detailed comparison with adjacent products/frameworks: docs/llm-generated-comparison.md
-
Author notes, build context, and design history: docs/author-notes.md
-
Runtime rationale: kogwistar/docs/ARD-custom-runtime-rationale.md
-
Local conversation walkthrough: docs/tutorials/conversation-pipeline-basics.md
-
Roadmap and research direction: docs/roadmap.md
-
Alternatively, let your AI agent read through and set up the credential/ keys and environment variables for you, and run the appropriate commands.
Core Features
- Graph/hypergraph-oriented memory and query surfaces.
- Knowledge can go outdated. Trace available knowledge/graph status back in any time.
- Workflow design stored as graph structure, with runtime, replay, and event-oriented execution seams.
- Support conversation execution events stored as hypergraph/graph
- CDC-oriented graph updates and replay workflows. (Observability is FREE, NOT freemium!)
- Provenance-heavy first class primitives with lifecycle-aware and temporal retrieval support.
- Multiple storage backends, including Chroma and PostgreSQL/pgvector paths. With dual-store eventual consistency or transactional atomicity.
- MCP/ REST tooling surface for graph query, extraction, and admin operations.
- Visualization helpers for D3 payloads.
- Security- and governance-oriented primitives, including RBAC/namespaces, privacy guards for LLM paths, slice guards to prevent data leakage, and workflow seams that can host policy/approval logic.
- Since everything is node and each node has provenance and embeddings, besides graph algorithms, you can trace provenence down everything and semantically search trace logs, design nodes, conversation nodes. Future conversation can semantically search past history for wisdom.
How This Differs
- Unlike typical agent products, this repo centers a unified graph/hypergraph substrate, more than only chat, skills, or tool orchestration.
- Unlike workflow-first frameworks, it treats provenance, replay, and event history (event source) as part of the core data model rather than secondary runtime features.
- Unlike memory-only agent stacks, it can also act as the substrate beneath a policy, approval, and governance semantics layer.
- It can support multiple product layers on top of the same core, from appl
