Architecture

Ixchel shares a common architecture that balances simplicity with power.

Overview

┌─────────────────────────────────────────────────────────────────────┐
│                         CLI Tools Layer                              │
│                                                                      │
│   ixchel                demo-got                                  │
│   (knowledge weaving)   (example project)                         │
│                                                                      │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
┌──────────────────────────────┴──────────────────────────────────────┐
│                        Shared Libraries                              │
│                                                                      │
│   ix-id     ix-config     ix-embeddings     ix-core                │
│   (hash IDs) (settings)   (embedders)       (domain logic)         │
│                                                                      │
└──────────────────────────────┬──────────────────────────────────────┘
                               │
┌──────────────────────────────┴──────────────────────────────────────┐
│                           HelixDB                                    │
│                                                                      │
│   Graph Engine    Vector Search    BM25 Index    LMDB Storage       │
│   (traversals)    (HNSW)           (text)        (persistence)      │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Data Flow

Every tool follows the same pattern:

Write Path

User/agent creates or modifies data via CLI
Changes are written to git-tracked files (Markdown/YAML)
Data is indexed in HelixDB for fast querying
Embeddings are generated asynchronously

Read Path

Query comes in (keyword, semantic, or hybrid)
HelixDB returns results using appropriate index
Results are formatted for human or agent consumption

Sync Path

When you git pull new changes:

File watcher detects changes in tracked directories
Changed files are parsed and validated
HelixDB is updated to match file state
Embeddings are regenerated if text content changed

Technology Stack

Component	Technology	Why
Language	Rust	Performance, safety, HelixDB compatibility
Database	HelixDB	Graph + vector + BM25 in one
Embeddings	fastembed	Native Rust, offline, no server
CLI	clap	Standard Rust CLI framework
Git ops	gix	Pure Rust git implementation
Hashing	Blake3	Fast cryptographic hashing for IDs

Project Structure

ixchel/
├── apps/
│   ├── demo-got/            # Demo project (HelixDB + ix-embeddings)
│   ├── ix-cli/              # ixchel CLI (binary)
│   ├── ix-daemon/           # Background daemon + IPC (binary: ixcheld)
│   └── ix-mcp/              # ixchel MCP server
│
├── crates/
│   ├── ix-app/              # ixchel wiring layer
│   ├── ix-core/             # ixchel core library
│   ├── ix-storage-helixdb/  # HelixDB-backed cache/index for ixchel
│   ├── ix-id/               # Hash-based ID generation
│   ├── ix-config/           # Configuration loading
│   ├── ix-embeddings/       # Pluggable embedding providers
│   └── ix-helixdb-ops/       # HelixDB helper crate
│
├── docs/                   # This documentation site
│
├── Cargo.toml              # Workspace root
└── README.md

Each tool includes Kiro-style specifications in a specs/ directory:

requirements.md - User stories (EARS notation)
design.md - Technical architecture
tasks.md - Implementation roadmap

Architecture

On this page