System Architecture Library
Architecture is the discipline of controlling complexity before complexity controls the system. Especially in AI systems where non-determinism, latency, token economics, and orchestration drift compound exponentially.
01 Architecture Patterns
Orchestration Layer v2
Decoupled orchestration architecture separating routing logic from specialist execution layers through registry-driven capability injection.
Graph-Based RAG
Deterministic retrieval correction using StateGraph execution loops and parent-child context anchoring to prevent semantic smear during long-context retrieval.
Tiered Model Selector
Cost-aware inference routing that dynamically selects execution models based on semantic entropy, operational urgency, and system load.
02 memex system architecture
+----------------+ +-----------------+ +----------------+
| | | | | |
| Repositories +------>+ Watcher Process +------>+ Neo4j |
| (Source) | | (Ingestion) | | (Graph DB) |
| | | | | |
+-------+--------+ +--------+--------+ +-------+--------+
| | ^
| Git History | Tree-sitter AST | Relationships
v v |
+-------+--------+ +--------+--------+ |
| | | | |
| Git Watcher | | Semantic |---------------+
| (Background) | | Extractor |
| | | |
+----------------+ +-----------------+
|
v
+--------+--------+
| |
| MCP Server |
| (Context Hub) |
| |
+--------+--------+
|
| MCP Protocol
v
+--------+--------+
| |
| Agent Harnesses |
| (Claude/Gemini) |
| |
+-----------------+The memex architecture implements a bitemporal knowledge graph that continuously observes repository changes. It decouples the heavy lifting of AST parsing and semantic extraction from the real-time agent interaction loop.
03 Knowledge graph schema
| Node Type | Fields | Write Policy |
|---|---|---|
| Repository | id, url, branch, last_commit | LOCKED |
| Module | path, loc, language, hash | LOCKED |
| Symbol | name, type, scope, signature | LOCKED |
| Decision | context, rationale, trade-offs | OPEN |
| Dependency | target_id, type, version_req | LOCKED |
04 Data flow diagrams
Flow A: File Save → Graph
[ Watcher ] --(fs.event)--> [ Parser ] --(extract)--> [ Neo4j ]
| | |
+----(checksum)----------+-----(relationships)-----+Flow B: Commit → Decision
[ Git Hook ] --(post-commit)--> [ LLM Parser ] --(intent)--> [ Decision Node ]
| | |
+----(diff analysis)----------+-----(rationale)--------------+Flow C: Agent Write → Governance
[ Agent ] --(write_request)--> [ Governance Layer ] --(validate)--> [ Graph Store ]
| | |
+----(policy check)-----------+-----(audit log)------------------+05 Component map
memex/ ├── bin/ # Executable entry points ├── src/ │ ├── ingestion/ # Watchers and parsers │ │ ├── git.py # Git history analysis │ │ └── fs.py # Filesystem observation │ ├── storage/ # Graph and vector backends │ │ ├── neo4j.py # Temporal graph logic │ │ └── faiss.py # Semantic search index │ ├── server/ # MCP implementation │ │ └── tools.py # Agent tool definitions │ └── core/ # Shared logic └── tests/ # System validation