# sensesvoid/sqac architecture

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

- Interactive diagram: https://gitdiagram.com/sensesvoid/sqac
- Repository: https://github.com/sensesvoid/sqac

## Overview

SQAC turns taught facts, imported datasets, and project knowledge into portable .sqac cartridges, then retrieves a small set of relevant facts or skills for an LLM at query time. Its broader product also supports conversation offloading and session continuity, cartridge routing, code-graph exploration, and CLI, MCP, and HTTP access. The README documents several capabilities whose implementation excerpts were not sampled; those links are shown only where the documented workflow supports them.

Main entry points: [`sqac/store.py`](https://github.com/sensesvoid/sqac/blob/main/sqac/store.py) (Fact store), [`sqac_mcp.py`](https://github.com/sensesvoid/sqac/blob/main/sqac_mcp.py) (MCP tools), [`sqac/server.py`](https://github.com/sensesvoid/sqac/blob/main/sqac/server.py) (HTTP API), [`sqac/autobuild.py`](https://github.com/sensesvoid/sqac/blob/main/sqac/autobuild.py) (Project auto-build)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Knowledge authoring"]
  node_autobuild["Project auto-build<br/>[autobuild.py]"]
  node_watcher["Realtime tracking"]
  node_ingest["Dataset ingestion<br/>[ingest.py]"]
  node_skills["Skill routing<br/>[skills.py]"]
  node_codeparser["Code parser<br/>[parser.py]"]
end

subgraph group_runtime["Cartridge runtime"]
  node_store["Fact store<br/>[store.py]"]
  node_encoder["Address encoding<br/>[encoder.py]"]
  node_staticencoder["Semantic encoder<br/>[static_encoder.py]"]
  node_cartridge[("SQAC cartridge")]
  node_rack["Cartridge rack<br/>[rack.py]"]
  node_injection["Thought injection<br/>[injection.py]"]
end

subgraph group_context["Context lifecycle"]
  node_offloader["Context offloader<br/>[offloader.py]"]
  node_continuity["Session continuity<br/>[continuity.py]"]
  node_checkpoint["Checkpoints<br/>[checkpoint.py]"]
end

subgraph group_interfaces["Access and exploration"]
  node_cli["CLI<br/>[cli.py]"]
  node_mcp["MCP tools<br/>[sqac_mcp.py]"]
  node_http["HTTP API<br/>[server.py]"]
  node_codegraph["Code graph<br/>[graph.py]"]
  node_graphmcp["Graph MCP<br/>[graph_mcp.py]"]
end

node_user(("User / application"))
node_llm(("LLM"))

node_user -->|"teaches / queries"| node_cli
node_cli -->|"writes / searches"| node_store
node_user -->|"selects project"| node_autobuild
node_autobuild -->|"extracts knowledge"| node_store
node_watcher -->|"tracks changes"| node_autobuild
node_user -->|"provides dataset"| node_ingest
node_ingest -->|"adds records"| node_store
node_store -->|"encodes addresses"| node_encoder
node_store -.->|"semantic matching"| node_staticencoder
node_store -->|"saves / loads"| node_cartridge
node_rack -->|"routes cartridges"| node_cartridge
node_store -->|"routes skill hits"| node_skills
node_skills -->|"selects procedure"| node_injection
node_store -->|"provides retrieved context"| node_injection
node_injection -->|"injects procedure"| node_llm
node_store -->|"returns relevant facts"| node_llm
node_user -->|"requests memory tools"| node_mcp
node_mcp -->|"reads / writes"| node_store
node_user -->|"sends API requests"| node_http
node_http -->|"searches / teaches"| node_store
node_http -->|"routes named cartridge"| node_rack
node_user -->|"provides conversation"| node_offloader
node_offloader -->|"offloads / recalls turns"| node_store
node_continuity -->|"records session state"| node_checkpoint
node_mcp -->|"manages sessions"| node_continuity
node_user -->|"selects codebase"| node_codeparser
node_codeparser -->|"extracts symbols and edges"| node_codegraph
node_graphmcp -->|"queries code graph"| node_codegraph

click node_cli "https://github.com/sensesvoid/sqac/blob/main/sqac/cli.py"
click node_autobuild "https://github.com/sensesvoid/sqac/blob/main/sqac/autobuild.py"
click node_watcher "https://github.com/sensesvoid/sqac/blob/main/sqac/autobuild_watcher.py"
click node_ingest "https://github.com/sensesvoid/sqac/blob/main/sqac/ingest.py"
click node_skills "https://github.com/sensesvoid/sqac/blob/main/sqac/skills.py"
click node_store "https://github.com/sensesvoid/sqac/blob/main/sqac/store.py"
click node_encoder "https://github.com/sensesvoid/sqac/blob/main/sqac/encoder.py"
click node_staticencoder "https://github.com/sensesvoid/sqac/blob/main/sqac/static_encoder.py"
click node_rack "https://github.com/sensesvoid/sqac/blob/main/sqac/rack.py"
click node_offloader "https://github.com/sensesvoid/sqac/blob/main/sqac/offloader.py"
click node_continuity "https://github.com/sensesvoid/sqac/blob/main/sqac/continuity.py"
click node_checkpoint "https://github.com/sensesvoid/sqac/blob/main/sqac/checkpoint.py"
click node_injection "https://github.com/sensesvoid/sqac/blob/main/sqac/injection.py"
click node_mcp "https://github.com/sensesvoid/sqac/blob/main/sqac_mcp.py"
click node_http "https://github.com/sensesvoid/sqac/blob/main/sqac/server.py"
click node_codeparser "https://github.com/sensesvoid/sqac/blob/main/sqac/graph/parser.py"
click node_codegraph "https://github.com/sensesvoid/sqac/blob/main/sqac/graph/graph.py"
click node_graphmcp "https://github.com/sensesvoid/sqac/blob/main/sqac/graph_mcp.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_autobuild,node_watcher,node_ingest,node_skills,node_codeparser,node_user toneBlue
class node_store,node_encoder,node_staticencoder,node_cartridge,node_rack,node_injection toneAmber
class node_offloader,node_continuity,node_checkpoint toneMint
class node_cli,node_mcp,node_http,node_codegraph,node_graphmcp toneRose
class node_llm toneIndigo
```

## Components

### Knowledge authoring

- [Project auto-build](https://github.com/sensesvoid/sqac/blob/main/sqac/autobuild.py): `sqac/autobuild.py`
- [Realtime tracking](https://github.com/sensesvoid/sqac/blob/main/sqac/autobuild_watcher.py): `sqac/autobuild_watcher.py`
- [Dataset ingestion](https://github.com/sensesvoid/sqac/blob/main/sqac/ingest.py): `sqac/ingest.py`
- [Skill routing](https://github.com/sensesvoid/sqac/blob/main/sqac/skills.py): `sqac/skills.py`
- [Code parser](https://github.com/sensesvoid/sqac/blob/main/sqac/graph/parser.py): `sqac/graph/parser.py`

### Cartridge runtime

- [Fact store](https://github.com/sensesvoid/sqac/blob/main/sqac/store.py): `sqac/store.py`
- [Address encoding](https://github.com/sensesvoid/sqac/blob/main/sqac/encoder.py): `sqac/encoder.py`
- [Semantic encoder](https://github.com/sensesvoid/sqac/blob/main/sqac/static_encoder.py): `sqac/static_encoder.py`
- **SQAC cartridge**
- [Cartridge rack](https://github.com/sensesvoid/sqac/blob/main/sqac/rack.py): `sqac/rack.py`
- [Thought injection](https://github.com/sensesvoid/sqac/blob/main/sqac/injection.py): `sqac/injection.py`

### Context lifecycle

- [Context offloader](https://github.com/sensesvoid/sqac/blob/main/sqac/offloader.py): `sqac/offloader.py`
- [Session continuity](https://github.com/sensesvoid/sqac/blob/main/sqac/continuity.py): `sqac/continuity.py`
- [Checkpoints](https://github.com/sensesvoid/sqac/blob/main/sqac/checkpoint.py): `sqac/checkpoint.py`

### Access and exploration

- [CLI](https://github.com/sensesvoid/sqac/blob/main/sqac/cli.py): `sqac/cli.py`
- [MCP tools](https://github.com/sensesvoid/sqac/blob/main/sqac_mcp.py): `sqac_mcp.py`
- [HTTP API](https://github.com/sensesvoid/sqac/blob/main/sqac/server.py): `sqac/server.py`
- [Code graph](https://github.com/sensesvoid/sqac/blob/main/sqac/graph/graph.py): `sqac/graph/graph.py`
- [Graph MCP](https://github.com/sensesvoid/sqac/blob/main/sqac/graph_mcp.py): `sqac/graph_mcp.py`

### Other components

- **User / application**
- **LLM**

## Connections

- User / application → CLI: teaches / queries
- CLI → Fact store: writes / searches
- User / application → Project auto-build: selects project
- Project auto-build → Fact store: extracts knowledge
- Realtime tracking → Project auto-build: tracks changes
- User / application → Dataset ingestion: provides dataset
- Dataset ingestion → Fact store: adds records
- Fact store → Address encoding: encodes addresses
- Fact store → Semantic encoder: semantic matching
- Fact store → SQAC cartridge: saves / loads
- Cartridge rack → SQAC cartridge: routes cartridges
- Fact store → Skill routing: routes skill hits
- Skill routing → Thought injection: selects procedure
- Fact store → Thought injection: provides retrieved context
- Thought injection → LLM: injects procedure
- Fact store → LLM: returns relevant facts
- User / application → MCP tools: requests memory tools
- MCP tools → Fact store: reads / writes
- User / application → HTTP API: sends API requests
- HTTP API → Fact store: searches / teaches
- HTTP API → Cartridge rack: routes named cartridge
- User / application → Context offloader: provides conversation
- Context offloader → Fact store: offloads / recalls turns
- Session continuity → Checkpoints: records session state
- MCP tools → Session continuity: manages sessions
- User / application → Code parser: selects codebase
- Code parser → Code graph: extracts symbols and edges
- Graph MCP → Code graph: queries code graph