💾 SomaFractalMemory

Important

Distributed Long-Term Memory for Autonomous AI Agents

---

1. Identification

• Project: SomaFractalMemory
• Version: 0.2.0
• Classification: PROPRIETARY / COMMERCIAL SENSITIVE
• Status: Production Ready

2. System Overview

SomaFractalMemory is a distributed long-term memory service for AI agents. It provides persistent vector storage with semantic search, enabling agents to recall past experiences and learned knowledge across sessions.

2.1 Architectural Context

Core component of the Soma Cognitive Triad:

1. SomaBrain: Processing & Reasoning
2. SomaAgent01: Orchestration & Execution
3. SomaFractalMemory: Storage & Recall (This Repo)

2.2 Key Capabilities

• Semantic Search: 768-dim embeddings via Milvus.
• Hierarchical Memory: Episodes (raw), Semantic (facts), Summaries (patterns).
• Multi-Tenancy: Crypto-isolated namespaces.
• Fractal Organization: Weighted importance and degradation graphs.

---

3. Installation & Configuration

3.1 Prerequisites

• Python: 3.12+
• Docker: 24.0+
• PostgreSQL: 15+ (Metadata)
• Milvus: 2.3+ (Vectors)
• Redis: 7.0+ (Cache)
• HashiCorp Vault: (Optional, Recommended for Secrets)
• Open Policy Agent: (Optional, Recommended for AuthZ)

3.2 Quick Start (Production)

# 1. Clone & Setup
git clone https://github.com/somatechlat/somafractalmemory.git
cd somafractalmemory

# 2. Configure Environment
cp .env.example .env
# EDIT .env WITH REAL CREDENTIALS

# 3. Launch Stack
docker compose -f infra/standalone/docker-compose.yml up -d

3.3 Configuration Parameters

| Variable | Description | Default |

Variable	Description	Default
SOMA_API_PORT	API Service Port	10101
SOMA_POSTGRES_URL	Database Connection	postgresql://...
SOMA_MILVUS_HOST	Vector Store Host	localhost
SOMA_REDIS_HOST	Cache Host	localhost
SOMA_VAULT_URL	Vault URL (Secrets)	""
SOMA_OPA_URL	OPA URL (AuthZ)	http://opa:10818
SOMA_OPA_FAIL_OPEN	AuthZ Safety Mode	False (Fail Closed)

---

4. Operation Procedures

4.1 Production Run

# Start Django Server via Gunicorn/Uvicorn
gunicorn somafractalmemory.config.wsgi:application --bind 0.0.0.0:10101

4.2 Development Mode

# Run tests
pytest tests/

4.3 API Health Check

curl http://localhost:10101/healthz
# Returns: {"kv_store": true, "vector_store": true, "graph_store": true}

---

5. Interface Specification

5.1 REST API References

Store Memory

POST /memories

{
  "coord": "1.0,2.0,3.0",
  "payload": { "content": "User prefers dark mode" },
  "memory_type": "semantic"
}

Search Memory

POST /memories/search

{
  "query": "dark mode",
  "top_k": 5
}

---

6. Maintenance & Contribution

• License: Apache 2.0
• Maintainer: SomaTech LAT
• Issues: GitHub Issues