# rastogivaibhav/moolbase architecture

> Architecture diagram of the GitHub repository rastogivaibhav/moolbase, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rastogivaibhav/moolbase
- Repository: https://github.com/rastogivaibhav/moolbase

## Overview

MoolBase is a persistent evidence-aware memory and reasoning substrate for agents. Its principal workflow is to ingest observations into durable graph memory, retrieve evidence, assess competing explanations and contradictions, then expose a governed answer and an inspectable receipt. The graph also preserves documented policy-learning and vector-retrieval capabilities. Several implementation connections are based on the README rather than sampled call sites; those are marked dashed or omitted where the wiring is uncertain.

Main entry points: [`src/hypokosh_runtime.cpp`](https://github.com/rastogivaibhav/moolbase/blob/master/src/hypokosh_runtime.cpp) (Governed reasoning), [`src/db.cpp`](https://github.com/rastogivaibhav/moolbase/blob/master/src/db.cpp) (Persistent graph DB), [`src/learning.cpp`](https://github.com/rastogivaibhav/moolbase/blob/master/src/learning.cpp) (Learning episodes), [`clients/python/graphenedb_client.py`](https://github.com/rastogivaibhav/moolbase/blob/master/clients/python/graphenedb_client.py) (Python client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Application interfaces"]
  node_python["Python client"]
  node_http["HTTP server"]
  node_native["Native API<br/>[c_api.cpp]"]
end

subgraph group_memory["Evidence memory"]
  node_db[("Persistent graph DB<br/>[db.cpp]")]
  node_vector["Vector indexes<br/>[kdtree_index.hpp]"]
  node_relations["Relations and ontology"]
  node_resolution["Entity resolution"]
end

subgraph group_reasoning["Reasoning and governance"]
  node_runtime["Governed reasoning"]
  node_dialectic["Evidence expansion<br/>[dialectic.cpp]"]
  node_fibers["Evidence paths<br/>[fiber_bundle.cpp]"]
  node_stability["Stability assessment"]
  node_control["Epistemic control"]
  node_verification["Path verification<br/>[path_verifier.cpp]"]
  node_world["Model world<br/>[model_world.cpp]"]
  node_receipt["Decision receipts"]
end

subgraph group_learning["Policy learning"]
  node_learning_store["Learning episodes<br/>[learning.cpp]"]
  node_learning_policy["Policy evaluation<br/>[learning.cpp]"]
end

node_agent(("Agent application"))
node_outcome["Governed answer"]

node_agent -.->|"submits requests"| node_python
node_python -.->|"calls HTTP"| node_http
node_agent -.->|"drives native API"| node_native
node_http -.->|"serves memory"| node_db
node_native -.->|"accesses memory"| node_db
node_db -->|"uses indexes"| node_vector
node_db -.->|"stores graph relations"| node_relations
node_db -.->|"supports resolution"| node_resolution
node_agent -.->|"requests reasoning"| node_runtime
node_runtime -.->|"reads evidence"| node_db
node_runtime -.->|"expands evidence"| node_dialectic
node_dialectic -->|"builds paths"| node_fibers
node_runtime -->|"assesses stability"| node_stability
node_runtime -->|"governs decisions"| node_control
node_runtime -->|"verifies paths"| node_verification
node_runtime -->|"updates world"| node_world
node_runtime -.->|"records decision"| node_receipt
node_runtime -.->|"returns status"| node_outcome
node_agent -.->|"records outcomes"| node_learning_store
node_learning_store -->|"persists episodes"| node_db
node_learning_policy -.->|"evaluates episodes"| node_learning_store

click node_python "https://github.com/rastogivaibhav/moolbase/blob/master/clients/python/graphenedb_client.py"
click node_http "https://github.com/rastogivaibhav/moolbase/blob/master/tools/graphenedb_server.cpp"
click node_native "https://github.com/rastogivaibhav/moolbase/blob/master/src/c_api.cpp"
click node_db "https://github.com/rastogivaibhav/moolbase/blob/master/src/db.cpp"
click node_vector "https://github.com/rastogivaibhav/moolbase/blob/master/include/graphene/kdtree_index.hpp"
click node_relations "https://github.com/rastogivaibhav/moolbase/blob/master/src/relation_ontology.cpp"
click node_resolution "https://github.com/rastogivaibhav/moolbase/blob/master/src/entity_resolution.cpp"
click node_learning_store "https://github.com/rastogivaibhav/moolbase/blob/master/src/learning.cpp"
click node_runtime "https://github.com/rastogivaibhav/moolbase/blob/master/src/hypokosh_runtime.cpp"
click node_dialectic "https://github.com/rastogivaibhav/moolbase/blob/master/src/dialectic.cpp"
click node_fibers "https://github.com/rastogivaibhav/moolbase/blob/master/src/fiber_bundle.cpp"
click node_stability "https://github.com/rastogivaibhav/moolbase/blob/master/src/stability_critic.cpp"
click node_control "https://github.com/rastogivaibhav/moolbase/blob/master/src/epistemic_control.cpp"
click node_verification "https://github.com/rastogivaibhav/moolbase/blob/master/src/path_verifier.cpp"
click node_world "https://github.com/rastogivaibhav/moolbase/blob/master/src/model_world.cpp"
click node_receipt "https://github.com/rastogivaibhav/moolbase/blob/master/src/epistemic_receipt.cpp"
click node_learning_policy "https://github.com/rastogivaibhav/moolbase/blob/master/src/learning.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_python,node_http,node_native toneBlue
class node_db,node_vector,node_relations,node_resolution toneAmber
class node_runtime,node_dialectic,node_fibers,node_stability,node_control,node_verification,node_world,node_receipt toneMint
class node_learning_store,node_learning_policy toneRose
class node_agent,node_outcome toneIndigo
```

## Components

### Application interfaces

- [Python client](https://github.com/rastogivaibhav/moolbase/blob/master/clients/python/graphenedb_client.py): `clients/python/graphenedb_client.py`
- [HTTP server](https://github.com/rastogivaibhav/moolbase/blob/master/tools/graphenedb_server.cpp): `tools/graphenedb_server.cpp`
- [Native API](https://github.com/rastogivaibhav/moolbase/blob/master/src/c_api.cpp): `src/c_api.cpp`

### Evidence memory

- [Persistent graph DB](https://github.com/rastogivaibhav/moolbase/blob/master/src/db.cpp): `src/db.cpp`
- [Vector indexes](https://github.com/rastogivaibhav/moolbase/blob/master/include/graphene/kdtree_index.hpp): `include/graphene/kdtree_index.hpp`
- [Relations and ontology](https://github.com/rastogivaibhav/moolbase/blob/master/src/relation_ontology.cpp): `src/relation_ontology.cpp`
- [Entity resolution](https://github.com/rastogivaibhav/moolbase/blob/master/src/entity_resolution.cpp): `src/entity_resolution.cpp`

### Reasoning and governance

- [Governed reasoning](https://github.com/rastogivaibhav/moolbase/blob/master/src/hypokosh_runtime.cpp): `src/hypokosh_runtime.cpp`
- [Evidence expansion](https://github.com/rastogivaibhav/moolbase/blob/master/src/dialectic.cpp): `src/dialectic.cpp`
- [Evidence paths](https://github.com/rastogivaibhav/moolbase/blob/master/src/fiber_bundle.cpp): `src/fiber_bundle.cpp`
- [Stability assessment](https://github.com/rastogivaibhav/moolbase/blob/master/src/stability_critic.cpp): `src/stability_critic.cpp`
- [Epistemic control](https://github.com/rastogivaibhav/moolbase/blob/master/src/epistemic_control.cpp): `src/epistemic_control.cpp`
- [Path verification](https://github.com/rastogivaibhav/moolbase/blob/master/src/path_verifier.cpp): `src/path_verifier.cpp`
- [Model world](https://github.com/rastogivaibhav/moolbase/blob/master/src/model_world.cpp): `src/model_world.cpp`
- [Decision receipts](https://github.com/rastogivaibhav/moolbase/blob/master/src/epistemic_receipt.cpp): `src/epistemic_receipt.cpp`

### Policy learning

- [Learning episodes](https://github.com/rastogivaibhav/moolbase/blob/master/src/learning.cpp): `src/learning.cpp`
- [Policy evaluation](https://github.com/rastogivaibhav/moolbase/blob/master/src/learning.cpp): `src/learning.cpp`

### Other components

- **Agent application**
- **Governed answer**

## Connections

- Agent application → Python client: submits requests
- Python client → HTTP server: calls HTTP
- Agent application → Native API: drives native API
- HTTP server → Persistent graph DB: serves memory
- Native API → Persistent graph DB: accesses memory
- Persistent graph DB → Vector indexes: uses indexes (evidence: `src/db.cpp`)
- Persistent graph DB → Relations and ontology: stores graph relations
- Persistent graph DB → Entity resolution: supports resolution
- Agent application → Governed reasoning: requests reasoning
- Governed reasoning → Persistent graph DB: reads evidence
- Governed reasoning → Evidence expansion: expands evidence
- Evidence expansion → Evidence paths: builds paths
- Governed reasoning → Stability assessment: assesses stability
- Governed reasoning → Epistemic control: governs decisions
- Governed reasoning → Path verification: verifies paths
- Governed reasoning → Model world: updates world
- Governed reasoning → Decision receipts: records decision
- Governed reasoning → Governed answer: returns status
- Agent application → Learning episodes: records outcomes
- Learning episodes → Persistent graph DB: persists episodes
- Policy evaluation → Learning episodes: evaluates episodes (evidence: `src/learning.cpp`)
