Architecture of the Yachaq Assistant

Q: Do I need a specific language model?

The assistant is model-agnostic: SomaAgent01 connects any model through a standard interface. The assistant provides execution, reasoning and memory.

Q: What links SomaBrain and SomaFractalMemory?

The 768-dimension embedding vector (MEM_EMBED_DIM · EMBED_DIM · SOMA_VECTOR_DIM). SomaBrain reasons over it and SomaFractalMemory persists and searches it by similarity.

Why three
services

Independent scaling

Memory grows with usage; the orchestrator scales with load. Separate them and scale only what needs it.

Replaceable

Language generation is one more piece. Swap providers while keeping memory and orchestration intact.

Auditable

Each service is an Apache 2.0 repository with its own documented API and its own tests.

Execution.
Reasoning.
Recall.

01 · Orchestration and execution

SomaAgent01

The orchestrator. Receives a request, breaks it down, decides which tools to invoke and coordinates specialists. It is the layer that turns intent into actions inside multi-tenant environments.

somaagent01 ↗

Backend	Django 5.1 + Django Ninja
Frontend	Lit 3.x (Web Components)
Data	PostgreSQL 16 · Redis 7
Events	Kafka 3.7 (KRaft)
Vectors	Milvus 2.3
Identity	Keycloak 24 · SpiceDB · OPA
API	:20020 (Standalone)
Deployment	Standalone · soma-stack-net cluster · Kubernetes

02 · Processing and reasoning

SomaBrain

The brain. It holds working memory, consolidates what is learned and modulates attention. It uses hyperdimensional representations (HRR/BHDC) of 8,192 dimensions to retrieve context in O(1).

somabrain ↗

Runtime	Python 3.12
Cognitive core	HRR / BHDC · 8192 dimensions
Retrieval	O(1) by algebraic index
Native core	Rust · somabrain_rs
Secrets	Vault · managed in Vault
API	:30101
Port range	30100–30111

03 · Storage and recall

SomaFractalMemory

Long-term memory. It persists episodic and semantic memories in Milvus, searches them by similarity and exposes a fractal graph of relations for associative recall.

somafractalmemory ↗

Runtime	Python 3.12
Vectors	Milvus · 768 dimensions
Metadata	PostgreSQL · Redis
Auth	Bearer SOMA_API_TOKEN + X-Soma-Tenant
API	:10101
Port range	10xxx

768 dimensions

The embedding vector is the contract between reasoning and memory. The three services share the same dimension.

Set it identically across the stack so semantic recall stays precise. The shared dimension is the key piece of the integration, and it lives in one value.

Variable	MEM_EMBED_DIM · EMBED_DIM · SOMA_VECTOR_DIM
Value	768
Must match in	SomaAgent01 · SomaBrain · SomaFractalMemory

.env — the seam

# SomaAgent01
MEM_EMBED_DIM=768

# SomaBrain
EMBED_DIM=768

# SomaFractalMemory
SOMA_VECTOR_DIM=768
SOMA_API_TOKEN=your-token

The journey
of a question

Input

SomaAgent01 receives the user request and the session context.

Plan

It breaks down the task and decides tools and specialists.

Recall

SomaFractalMemory returns memories by 768-dim semantic similarity.

Reasoning

SomaBrain consolidates the context in its hyperdimensional working memory.

Answer

The LLM writes with the retrieved context and the cycle is persisted for next time.

Common
questions

Do I need a specific language model?

The assistant is model-agnostic. SomaAgent01 connects any model through a standard interface: the assistant provides execution, reasoning and memory.

Can I self-host the assistant?

Yes. All three repositories are Apache 2.0 and deploy with Docker Compose on your own infrastructure, with full control of your stack.

What links SomaBrain and SomaFractalMemory?

The 768-dimension embedding vector. SomaBrain reasons over it and SomaFractalMemory persists and searches it by similarity. It must be set identically across the three services.

Do the repositories need to be side by side?

Yes. For the integrated deployment the three repositories live in the same parent directory. up-cluster.sh creates the shared soma-stack-net network and brings up the full assistant in order: memory → brain → orchestrator.

Fullsystem

Why threeservices