# swagduck/mvdm architecture

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

- Interactive diagram: https://gitdiagram.com/swagduck/mvdm
- Repository: https://github.com/swagduck/mvdm

## Overview

MVDM is a deterministic, model-independent cognitive architecture with a bilingual local chat interface. The principal user workflow is entering a turn in the chat CLI, interpreting it into structured language/propositional representations, grounding and verifying a planned response against stored knowledge, then returning a grounded reply; withheld replies are logged rather than stored as self-utterances. Separate capabilities cover executive cognitive cycles, memory consolidation, identity, and autonomous development. Dashed links indicate runtime wiring not established by the supplied excerpts or README.

Main entry points: [`mvdm/app/chat.py`](https://github.com/swagduck/mvdm/blob/main/mvdm/app/chat.py) (Chat CLI), [`mvdm/executive/loop.py`](https://github.com/swagduck/mvdm/blob/main/mvdm/executive/loop.py) (Executive loop), [`mvdm/language/ingest.py`](https://github.com/swagduck/mvdm/blob/main/mvdm/language/ingest.py) (Utterance ingestion), [`mvdm/development/engine.py`](https://github.com/swagduck/mvdm/blob/main/mvdm/development/engine.py) (Development engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Chat interface"]
  node_chat["Chat CLI<br/>[chat.py]"]
end

subgraph group_language["Language processing"]
  node_language_runtime["Language runtime<br/>[runtime.py]"]
  node_ingest["Utterance ingestion<br/>[ingest.py]"]
  node_tokenizer["Unicode tokenizer<br/>[tokenizer.py]"]
  node_lexicon["Bilingual lexicon<br/>[lexicon.py]"]
  node_extract["Fact extraction<br/>[extract.py]"]
  node_responder["Response planning<br/>[respond.py]"]
end

subgraph group_cognition["Cognitive runtime"]
  node_workspace["Working workspace<br/>[workspace.py]"]
  node_baseline["Deterministic baseline<br/>[deterministic.py]"]
  node_loop["Executive loop<br/>[loop.py]"]
  node_policy["Action policy<br/>[policy.py]"]
  node_value["Value appraisal<br/>[contracts.py]"]
end

subgraph group_knowledge["Knowledge and development"]
  node_frames["Propositional frames<br/>[frames.py]"]
  node_episodic["Episodic memory<br/>[episodic.py]"]
  node_consolidation["Memory consolidation<br/>[consolidation.py]"]
  node_identity["Identity model<br/>[model.py]"]
  node_beliefs["Belief graph<br/>[belief_graph.py]"]
  node_development["Development engine<br/>[engine.py]"]
  node_constructions["Construction inducer<br/>[constructions.py]"]
  node_registry["Model registry<br/>[registry.py]"]
end

subgraph group_persistence["Persistence and trace"]
  node_storage[("SQLite WAL store<br/>[sqlite_store.py]")]
  node_events["Cognitive event bus<br/>[events.py]"]
end

node_user(("User"))

node_user -->|"enters turn"| node_chat
node_chat -.->|"plans reply"| node_responder
node_chat -->|"verifies reply"| node_storage
node_chat -->|"inspects beliefs"| node_beliefs
node_chat -->|"inspects development"| node_development
node_chat -->|"requests rollback"| node_registry
node_language_runtime -.->|"dispatches input"| node_ingest
node_ingest -->|"tokenizes text"| node_tokenizer
node_ingest -->|"uses vocabulary"| node_lexicon
node_ingest -->|"extracts meaning"| node_extract
node_extract -->|"parses frames"| node_frames
node_responder -->|"uses structure"| node_frames
node_responder -->|"grounds claims"| node_beliefs
node_baseline -->|"appraises input"| node_value
node_loop -->|"orchestrates cycle"| node_workspace
node_loop -->|"retrieves episodes"| node_episodic
node_loop -.->|"requests decision"| node_policy
node_loop -.->|"runs consolidation"| node_consolidation
node_loop -.->|"updates identity"| node_identity
node_episodic -->|"reads and writes"| node_storage
node_identity -->|"derives from episodes"| node_episodic
node_identity -->|"reads entities"| node_storage
node_development -->|"uses induction"| node_constructions
node_registry -->|"reconstructs model"| node_development
node_development -->|"replays records"| node_storage
node_chat -->|"logs withheld reply"| node_events

click node_chat "https://github.com/swagduck/mvdm/blob/main/mvdm/app/chat.py"
click node_language_runtime "https://github.com/swagduck/mvdm/blob/main/mvdm/language/runtime.py"
click node_ingest "https://github.com/swagduck/mvdm/blob/main/mvdm/language/ingest.py"
click node_tokenizer "https://github.com/swagduck/mvdm/blob/main/mvdm/language/tokenizer.py"
click node_lexicon "https://github.com/swagduck/mvdm/blob/main/mvdm/language/lexicon.py"
click node_extract "https://github.com/swagduck/mvdm/blob/main/mvdm/language/extract.py"
click node_frames "https://github.com/swagduck/mvdm/blob/main/mvdm/reasoning/frames.py"
click node_responder "https://github.com/swagduck/mvdm/blob/main/mvdm/language/respond.py"
click node_workspace "https://github.com/swagduck/mvdm/blob/main/mvdm/core/workspace.py"
click node_baseline "https://github.com/swagduck/mvdm/blob/main/mvdm/baseline/deterministic.py"
click node_loop "https://github.com/swagduck/mvdm/blob/main/mvdm/executive/loop.py"
click node_policy "https://github.com/swagduck/mvdm/blob/main/mvdm/executive/policy.py"
click node_episodic "https://github.com/swagduck/mvdm/blob/main/mvdm/memory/episodic.py"
click node_consolidation "https://github.com/swagduck/mvdm/blob/main/mvdm/memory/consolidation.py"
click node_identity "https://github.com/swagduck/mvdm/blob/main/mvdm/identity/model.py"
click node_beliefs "https://github.com/swagduck/mvdm/blob/main/mvdm/reasoning/belief_graph.py"
click node_development "https://github.com/swagduck/mvdm/blob/main/mvdm/development/engine.py"
click node_constructions "https://github.com/swagduck/mvdm/blob/main/mvdm/development/constructions.py"
click node_registry "https://github.com/swagduck/mvdm/blob/main/mvdm/development/registry.py"
click node_value "https://github.com/swagduck/mvdm/blob/main/mvdm/value/contracts.py"
click node_storage "https://github.com/swagduck/mvdm/blob/main/mvdm/storage/sqlite_store.py"
click node_events "https://github.com/swagduck/mvdm/blob/main/mvdm/core/events.py"

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_chat,node_user toneBlue
class node_language_runtime,node_ingest,node_tokenizer,node_lexicon,node_extract,node_responder toneAmber
class node_workspace,node_baseline,node_loop,node_policy,node_value toneMint
class node_frames,node_episodic,node_consolidation,node_identity,node_beliefs,node_development,node_constructions,node_registry toneRose
class node_storage,node_events toneIndigo
```

## Components

### Chat interface

- [Chat CLI](https://github.com/swagduck/mvdm/blob/main/mvdm/app/chat.py): `mvdm/app/chat.py`

### Language processing

- [Language runtime](https://github.com/swagduck/mvdm/blob/main/mvdm/language/runtime.py): `mvdm/language/runtime.py`
- [Utterance ingestion](https://github.com/swagduck/mvdm/blob/main/mvdm/language/ingest.py): `mvdm/language/ingest.py`
- [Unicode tokenizer](https://github.com/swagduck/mvdm/blob/main/mvdm/language/tokenizer.py): `mvdm/language/tokenizer.py`
- [Bilingual lexicon](https://github.com/swagduck/mvdm/blob/main/mvdm/language/lexicon.py): `mvdm/language/lexicon.py`
- [Fact extraction](https://github.com/swagduck/mvdm/blob/main/mvdm/language/extract.py): `mvdm/language/extract.py`
- [Response planning](https://github.com/swagduck/mvdm/blob/main/mvdm/language/respond.py): `mvdm/language/respond.py`

### Cognitive runtime

- [Working workspace](https://github.com/swagduck/mvdm/blob/main/mvdm/core/workspace.py): `mvdm/core/workspace.py`
- [Deterministic baseline](https://github.com/swagduck/mvdm/blob/main/mvdm/baseline/deterministic.py): `mvdm/baseline/deterministic.py`
- [Executive loop](https://github.com/swagduck/mvdm/blob/main/mvdm/executive/loop.py): `mvdm/executive/loop.py`
- [Action policy](https://github.com/swagduck/mvdm/blob/main/mvdm/executive/policy.py): `mvdm/executive/policy.py`
- [Value appraisal](https://github.com/swagduck/mvdm/blob/main/mvdm/value/contracts.py): `mvdm/value/contracts.py`

### Knowledge and development

- [Propositional frames](https://github.com/swagduck/mvdm/blob/main/mvdm/reasoning/frames.py): `mvdm/reasoning/frames.py`
- [Episodic memory](https://github.com/swagduck/mvdm/blob/main/mvdm/memory/episodic.py): `mvdm/memory/episodic.py`
- [Memory consolidation](https://github.com/swagduck/mvdm/blob/main/mvdm/memory/consolidation.py): `mvdm/memory/consolidation.py`
- [Identity model](https://github.com/swagduck/mvdm/blob/main/mvdm/identity/model.py): `mvdm/identity/model.py`
- [Belief graph](https://github.com/swagduck/mvdm/blob/main/mvdm/reasoning/belief_graph.py): `mvdm/reasoning/belief_graph.py`
- [Development engine](https://github.com/swagduck/mvdm/blob/main/mvdm/development/engine.py): `mvdm/development/engine.py`
- [Construction inducer](https://github.com/swagduck/mvdm/blob/main/mvdm/development/constructions.py): `mvdm/development/constructions.py`
- [Model registry](https://github.com/swagduck/mvdm/blob/main/mvdm/development/registry.py): `mvdm/development/registry.py`

### Persistence and trace

- [SQLite WAL store](https://github.com/swagduck/mvdm/blob/main/mvdm/storage/sqlite_store.py): `mvdm/storage/sqlite_store.py`
- [Cognitive event bus](https://github.com/swagduck/mvdm/blob/main/mvdm/core/events.py): `mvdm/core/events.py`

### Other components

- **User**

## Connections

- User → Chat CLI: enters turn
- Chat CLI → Response planning: plans reply (evidence: `mvdm/app/chat.py`)
- Chat CLI → SQLite WAL store: verifies reply (evidence: `mvdm/app/chat.py`)
- Chat CLI → Belief graph: inspects beliefs (evidence: `mvdm/app/chat.py`)
- Chat CLI → Development engine: inspects development (evidence: `mvdm/app/chat.py`)
- Chat CLI → Model registry: requests rollback (evidence: `mvdm/app/chat.py`)
- Language runtime → Utterance ingestion: dispatches input (evidence: `mvdm/language/runtime.py`)
- Utterance ingestion → Unicode tokenizer: tokenizes text (evidence: `mvdm/language/ingest.py`)
- Utterance ingestion → Bilingual lexicon: uses vocabulary (evidence: `mvdm/language/ingest.py`)
- Utterance ingestion → Fact extraction: extracts meaning (evidence: `mvdm/language/ingest.py`)
- Fact extraction → Propositional frames: parses frames (evidence: `mvdm/language/extract.py`)
- Response planning → Propositional frames: uses structure (evidence: `mvdm/language/respond.py`)
- Response planning → Belief graph: grounds claims (evidence: `mvdm/language/respond.py`)
- Deterministic baseline → Value appraisal: appraises input (evidence: `mvdm/baseline/deterministic.py`)
- Executive loop → Working workspace: orchestrates cycle (evidence: `mvdm/executive/loop.py`)
- Executive loop → Episodic memory: retrieves episodes (evidence: `mvdm/executive/loop.py`)
- Executive loop → Action policy: requests decision (evidence: `mvdm/executive/loop.py`)
- Executive loop → Memory consolidation: runs consolidation (evidence: `mvdm/executive/loop.py`)
- Executive loop → Identity model: updates identity (evidence: `mvdm/executive/loop.py`)
- Episodic memory → SQLite WAL store: reads and writes (evidence: `mvdm/memory/episodic.py`)
- Identity model → Episodic memory: derives from episodes (evidence: `mvdm/identity/model.py`)
- Identity model → SQLite WAL store: reads entities (evidence: `mvdm/identity/model.py`)
- Development engine → Construction inducer: uses induction (evidence: `mvdm/development/engine.py`)
- Model registry → Development engine: reconstructs model (evidence: `mvdm/development/registry.py`)
- Development engine → SQLite WAL store: replays records (evidence: `mvdm/development/engine.py`)
- Chat CLI → Cognitive event bus: logs withheld reply (evidence: `mvdm/app/chat.py`)