# pliablerigidity/kosine architecture

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

- Interactive diagram: https://gitdiagram.com/pliablerigidity/kosine
- Repository: https://github.com/pliablerigidity/kosine

## Overview

KOSINE is a local-first, graph-native memory system. Users enter through the CLI, terminal UI, REST API, or agent integrations; they create or import structured memories into an isolated Brain, then query and explore those memories. SQLite is the documented source of truth. The README also describes optional AI and Kuzu support, exports, capture, and several specialized memory layers. Some subsystems are represented by documented capabilities and tree paths rather than sampled implementation; their internal wiring is not inferred.

Main entry points: [`kos/database.py`](https://github.com/pliablerigidity/kosine/blob/main/kos/database.py) (SQLite Database), [`kos.py`](https://github.com/pliablerigidity/kosine/blob/main/kos.py) (CLI), [`kos/importer.py`](https://github.com/pliablerigidity/kosine/blob/main/kos/importer.py) (Markdown Import), [`kos/agent_tools.py`](https://github.com/pliablerigidity/kosine/blob/main/kos/agent_tools.py) (Agent Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["CLI<br/>[kos.py]"]
  node_tui["Terminal UI<br/>[tui.py]"]
  node_api["REST API<br/>[api.py]"]
  node_agent["Agent Tools<br/>[agent_tools.py]"]
  node_mcp["MCP Server<br/>[mcp_server.py]"]
end

subgraph group_memory["Memory Core"]
  node_brain["Brain Runtime<br/>[brain.py]"]
  node_intent["Input Planner<br/>[intent.py]"]
  node_database[("SQLite Database<br/>[database.py]")]
end

subgraph group_retrieval["Retrieval and Views"]
  node_query["Query Engine<br/>[query.py]"]
  node_context["Context Graph<br/>[context_graph.py]"]
  node_llm["Local LLM<br/>[llm.py]"]
  node_viewer["Graph Viewer<br/>[graph_viewer.py]"]
end

subgraph group_extensions["Import and Memory Layers"]
  node_capture["Inbox Capture<br/>[capture.py]"]
  node_vault["Vault Sync<br/>[vault.py]"]
  node_importer["Markdown Import<br/>[importer.py]"]
  node_extractor["Knowledge Extraction"]
  node_semantic["Semantic Memory<br/>[semantic.py]"]
  node_episodic["Episodic Memory<br/>[episodic.py]"]
  node_procedural["Procedural Memory<br/>[procedural.py]"]
  node_reasoning["Reasoning Graph<br/>[reasoning_graph.py]"]
  node_export["Markdown Export<br/>[export_md.py]"]
  node_kuzu[("Kuzu Backend<br/>[kg.py]")]
end

node_user(("Person"))

node_user -->|"uses"| node_cli
node_user -->|"uses"| node_tui
node_user -->|"sends requests"| node_api
node_cli -->|"selects Brain"| node_brain
node_cli -->|"plans input"| node_intent
node_intent -->|"reads and writes"| node_database
node_api -->|"dispatches tools"| node_agent
node_agent -->|"reads and writes"| node_database
node_cli -->|"runs queries"| node_query
node_query -->|"searches memory"| node_database
node_cli -->|"asks questions"| node_llm
node_llm -->|"builds context"| node_context
node_context -->|"retrieves graph"| node_database
node_cli -->|"opens graph"| node_viewer
node_viewer -->|"reads graph data"| node_database
node_cli -->|"imports vault"| node_vault
node_vault -->|"delegates import"| node_importer
node_importer -->|"stores documents"| node_database
node_importer -->|"extracts knowledge"| node_extractor
node_extractor -->|"creates memories"| node_database
node_cli -->|"captures notes"| node_capture
node_cli -->|"exports Markdown"| node_export
node_database -.->|"supports concepts"| node_semantic
node_database -.->|"supports episodes"| node_episodic
node_database -.->|"supports workflows"| node_procedural
node_database -.->|"supports traces"| node_reasoning
node_database -.->|"optional projection"| node_kuzu
node_mcp -->|"uses tool layer"| node_agent

click node_cli "https://github.com/pliablerigidity/kosine/blob/main/kos.py"
click node_tui "https://github.com/pliablerigidity/kosine/blob/main/kos/tui.py"
click node_api "https://github.com/pliablerigidity/kosine/blob/main/kos/api.py"
click node_agent "https://github.com/pliablerigidity/kosine/blob/main/kos/agent_tools.py"
click node_mcp "https://github.com/pliablerigidity/kosine/blob/main/kos/mcp_server.py"
click node_brain "https://github.com/pliablerigidity/kosine/blob/main/kos/brain.py"
click node_intent "https://github.com/pliablerigidity/kosine/blob/main/kos/intent.py"
click node_database "https://github.com/pliablerigidity/kosine/blob/main/kos/database.py"
click node_query "https://github.com/pliablerigidity/kosine/blob/main/kos/query.py"
click node_context "https://github.com/pliablerigidity/kosine/blob/main/kos/context_graph.py"
click node_llm "https://github.com/pliablerigidity/kosine/blob/main/kos/llm.py"
click node_viewer "https://github.com/pliablerigidity/kosine/blob/main/kos/graph_viewer.py"
click node_capture "https://github.com/pliablerigidity/kosine/blob/main/kos/capture.py"
click node_vault "https://github.com/pliablerigidity/kosine/blob/main/kos/vault.py"
click node_importer "https://github.com/pliablerigidity/kosine/blob/main/kos/importer.py"
click node_extractor "https://github.com/pliablerigidity/kosine/blob/main/kos/knowledge_extractor.py"
click node_semantic "https://github.com/pliablerigidity/kosine/blob/main/kos/semantic.py"
click node_episodic "https://github.com/pliablerigidity/kosine/blob/main/kos/episodic.py"
click node_procedural "https://github.com/pliablerigidity/kosine/blob/main/kos/procedural.py"
click node_reasoning "https://github.com/pliablerigidity/kosine/blob/main/kos/reasoning_graph.py"
click node_export "https://github.com/pliablerigidity/kosine/blob/main/kos/export_md.py"
click node_kuzu "https://github.com/pliablerigidity/kosine/blob/main/kos/kg.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_cli,node_tui,node_api,node_agent,node_mcp toneBlue
class node_brain,node_intent,node_database toneAmber
class node_query,node_context,node_llm,node_viewer toneMint
class node_capture,node_vault,node_importer,node_extractor,node_semantic,node_episodic,node_procedural,node_reasoning,node_export,node_kuzu toneRose
class node_user toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/pliablerigidity/kosine/blob/main/kos.py): `kos.py`
- [Terminal UI](https://github.com/pliablerigidity/kosine/blob/main/kos/tui.py): `kos/tui.py`
- [REST API](https://github.com/pliablerigidity/kosine/blob/main/kos/api.py): `kos/api.py`
- [Agent Tools](https://github.com/pliablerigidity/kosine/blob/main/kos/agent_tools.py): `kos/agent_tools.py`
- [MCP Server](https://github.com/pliablerigidity/kosine/blob/main/kos/mcp_server.py): `kos/mcp_server.py`

### Memory Core

- [Brain Runtime](https://github.com/pliablerigidity/kosine/blob/main/kos/brain.py): `kos/brain.py`
- [Input Planner](https://github.com/pliablerigidity/kosine/blob/main/kos/intent.py): `kos/intent.py`
- [SQLite Database](https://github.com/pliablerigidity/kosine/blob/main/kos/database.py): `kos/database.py`

### Retrieval and Views

- [Query Engine](https://github.com/pliablerigidity/kosine/blob/main/kos/query.py): `kos/query.py`
- [Context Graph](https://github.com/pliablerigidity/kosine/blob/main/kos/context_graph.py): `kos/context_graph.py`
- [Local LLM](https://github.com/pliablerigidity/kosine/blob/main/kos/llm.py): `kos/llm.py`
- [Graph Viewer](https://github.com/pliablerigidity/kosine/blob/main/kos/graph_viewer.py): `kos/graph_viewer.py`

### Import and Memory Layers

- [Inbox Capture](https://github.com/pliablerigidity/kosine/blob/main/kos/capture.py): `kos/capture.py`
- [Vault Sync](https://github.com/pliablerigidity/kosine/blob/main/kos/vault.py): `kos/vault.py`
- [Markdown Import](https://github.com/pliablerigidity/kosine/blob/main/kos/importer.py): `kos/importer.py`
- [Knowledge Extraction](https://github.com/pliablerigidity/kosine/blob/main/kos/knowledge_extractor.py): `kos/knowledge_extractor.py`
- [Semantic Memory](https://github.com/pliablerigidity/kosine/blob/main/kos/semantic.py): `kos/semantic.py`
- [Episodic Memory](https://github.com/pliablerigidity/kosine/blob/main/kos/episodic.py): `kos/episodic.py`
- [Procedural Memory](https://github.com/pliablerigidity/kosine/blob/main/kos/procedural.py): `kos/procedural.py`
- [Reasoning Graph](https://github.com/pliablerigidity/kosine/blob/main/kos/reasoning_graph.py): `kos/reasoning_graph.py`
- [Markdown Export](https://github.com/pliablerigidity/kosine/blob/main/kos/export_md.py): `kos/export_md.py`
- [Kuzu Backend](https://github.com/pliablerigidity/kosine/blob/main/kos/kg.py): `kos/kg.py`

### Other components

- **Person**

## Connections

- Person → CLI: uses
- Person → Terminal UI: uses
- Person → REST API: sends requests
- CLI → Brain Runtime: selects Brain (evidence: `kos.py`)
- CLI → Input Planner: plans input (evidence: `kos.py`)
- Input Planner → SQLite Database: reads and writes (evidence: `kos/intent.py`)
- REST API → Agent Tools: dispatches tools (evidence: `kos/agent_tools.py`)
- Agent Tools → SQLite Database: reads and writes (evidence: `kos/agent_tools.py`)
- CLI → Query Engine: runs queries (evidence: `kos.py`)
- Query Engine → SQLite Database: searches memory (evidence: `kos/query.py`)
- CLI → Local LLM: asks questions (evidence: `kos.py`)
- Local LLM → Context Graph: builds context (evidence: `kos/llm.py`)
- Context Graph → SQLite Database: retrieves graph (evidence: `kos/context_graph.py`)
- CLI → Graph Viewer: opens graph (evidence: `kos.py`)
- Graph Viewer → SQLite Database: reads graph data (evidence: `kos/graph_viewer.py`)
- CLI → Vault Sync: imports vault (evidence: `kos.py`)
- Vault Sync → Markdown Import: delegates import (evidence: `kos/vault.py`)
- Markdown Import → SQLite Database: stores documents (evidence: `kos/importer.py`)
- Markdown Import → Knowledge Extraction: extracts knowledge (evidence: `kos/importer.py`)
- Knowledge Extraction → SQLite Database: creates memories (evidence: `kos/knowledge_extractor.py`)
- CLI → Inbox Capture: captures notes (evidence: `kos.py`)
- CLI → Markdown Export: exports Markdown (evidence: `kos.py`)
- SQLite Database → Semantic Memory: supports concepts
- SQLite Database → Episodic Memory: supports episodes
- SQLite Database → Procedural Memory: supports workflows
- SQLite Database → Reasoning Graph: supports traces
- SQLite Database → Kuzu Backend: optional projection
- MCP Server → Agent Tools: uses tool layer (evidence: `kos/agent_tools.py`)
