soma-wisdom 0.5.0

SOMA: Somatic Wisdom Architecture — Wisdom over Memory

SOMA — Somatic Wisdom Architecture

Wisdom over Memory — 智慧超越记忆
Framework-First Cognitive Architecture for AI Agents

---

SOMA is a lightweight, pluggable cognitive framework that gives AI agents the ability to think, not just retrieve. It organizes memory around an explicit wisdom framework — seven thinking laws that form a reasoning network, not a flat list. Laws chain through relations, combine into synthesized perspectives, and self-correct against cognitive bias. The result: agents that decompose problems systematically, activate relevant knowledge bidirectionally, and evolve their own reasoning over time.

Not "make AI remember more." Make AI understand deeper.

📖 中文文档 | Documentation | Contributing | Changelog

⚡ Five-Minute Integration

pip install soma-wisdom
python -m soma          # one-command verification

from soma import SOMA

soma = SOMA()                                        # zero-config start

soma.remember(
    "First-principles thinking: deconstruct to fundamentals...",
    context={"domain": "philosophy", "type": "theory"},
    importance=0.9,
)

answer = soma.respond("How to analyze our growth bottleneck?")
print(answer)

No API key required for mock mode. Set llm="deepseek-chat" (or any LiteLLM model) for real LLM responses.

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                         SOMA Agent (v0.5)                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │ WisdomEngine  │→│ActivationHub │→│     MemoryCore        │  │
│  │ · 关键词匹配  │  │ · 双向激活   │  │ · episodic/semantic   │  │
│  │ · 规律链传播  │  │ · 反视角检索 │  │ · skill/sqlite+vector │  │
│  │ · 组合模板    │  │ · 可用性修正 │  │ · 加权RRF+时间衰减    │  │
│  │ · 语义兜底    │  └──────────────┘  └──────────────────────┘  │
│  │ · 语境排序    │         │                  │                  │
│  └──────────────┘         ▼                  ▼                  │
│         │         ┌──────────────────────────────────────────┐   │
│         ▼         │          MetaEvolver                     │   │
│  ┌──────────┐     │ · 偏差检测 → 自动调权 → 技能固化          │   │
│  │复杂度评估 │     │ · 动态步长 · 反思追踪 · 规律发现         │   │
│  └──────────┘     └──────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────┘

Ten-Stage Wisdom Pipeline:
  Assess → Decompose → Chain → Combine → Semantic-fallback
         → Context-sort → Activate → Anti-bias → Synthesize → Evolve

Screenshots

🧠 Wisdom Chat  ·  📊 5D Benchmark  ·  💻 IDE Integration  ·  🔌 REST API

Wisdom Chat — 7条规律分解问题，双向记忆激活，LLM流式响应	5D Benchmark — 记忆/智慧/进化/伸缩/综合，竞品实时对比
IDE Integration — Claude Code / VS Code 一键接入，记忆自动持久化	REST API — FastAPI + SSE 流式，多模型管理，API Key 认证

Dashboard

Start the API server and open http://localhost:8765:

SOMA_API_KEY=test python dash/server.py

Vue 3 dashboard with i18n (English / 中文), 6 views: Chat · Framework · Memory · Analytics · Benchmark · Settings.

Installation

pip install soma-wisdom

Requires Python 3.10+. The embedding engine uses ONNX Runtime for CPU inference — no CUDA, no Docker, no external services.

First run downloads a small ONNX model (~100 MB, Chinese-English bilingual).

python -m soma          # verify everything works in one command
soma-quickstart         # or use the CLI entry point

Core Concepts

1. Wisdom Framework — 7 Thinking Laws

Law	Description	Weight
first_principles	Reduce to fundamentals, derive from base elements	0.90
systems_thinking	See interconnected wholes, identify feedback loops	0.85
contradiction_analysis	Find opposing forces, identify principal contradictions	0.80
pareto_principle	Focus on the vital 20% that drives 80% of outcomes	0.75
inversion	Think backwards — how could this fail?	0.70
analogical_reasoning	Map structures across domains	0.65
evolutionary_lens	Observe change over time, identify lifecycle stages	0.60

Customize in wisdom_laws.yaml (bundled in the package — always available).

New in v0.5: Laws are no longer a flat list — they form a reasoning network. When a law triggers, its relations propagate activation to related laws (×0.35–0.50 bonus). When two laws fire together, synthesized perspectives emerge (e.g., "First Principles × Systems Thinking → Root-Cause System Analysis").

2. Bidirectional Activation — Hybrid RRF

Memories are matched through weighted Reciprocal Rank Fusion:

• Vector semantic similarity (×2 weight) via ONNX embeddings
• Keyword exact match (×1 weight)

Both directions compete and complement, producing true relevance scores.

3. Meta-Evolution — Self-Optimization

SOMA tracks success/failure of each thinking law across sessions. Every 10 sessions, evolve() automatically:

• Bias detection: laws used >40% of the time get penalized (-0.05) to prevent thinking ruts; underused high-success laws get boosted (+0.03)
• Dynamic step sizing: adjustment magnitude scales with sample count (0.01 → 0.02 → 0.03), replacing fixed ±0.02
• Skill solidification: successful (law, domain, outcome) patterns become permanent skills after 3+ occurrences

4. Memory Types

Type	Storage	Search
Episodic	SQLite + vector BLOB	Hybrid (semantic + keyword RRF)
Semantic	SQLite triple store	Keyword + graph traversal
Skill	SQLite pattern store	Keyword + domain matching

API Reference

SOMA Facade (Python SDK)

from soma import SOMA

soma = SOMA(
    framework_config=None,        # default: bundled wisdom_laws.yaml
    llm="deepseek-chat",          # LiteLLM model string
    use_vector_search=True,       # ONNX semantic search
    persist_dir="soma_data",      # persistence directory
    recall_threshold=0.01,        # minimum activation score
    top_k=5,                      # default recall count
)

# Wisdom pipeline
soma.respond(problem: str) -> str
soma.chat(problem: str) -> dict          # structured: foci + memories + weights

# Memory operations
soma.remember(content, context, importance) -> str  # returns memory_id
soma.remember_semantic(subject, predicate, object_, confidence)
soma.query_memory(query: str, top_k: int) -> list

# Introspection & evolution
soma.decompose(problem: str) -> list     # show thinking dimensions
soma.reflect(task_id, outcome) -> None   # record outcome for evolution
soma.evolve() -> list                    # trigger automatic weight adjustment
soma.get_weights() -> dict               # current law weights
soma.adjust_weight(law_id, new_weight)   # manual override
soma.discover_laws() -> dict | None      # autonomous law discovery
soma.approve_law(candidate) -> bool      # approve a discovered law
soma.stats -> dict                       # memory store statistics

REST API (Language-Agnostic)

# Start server
SOMA_API_KEY=your-key python dash/server.py    # → http://localhost:8765

# Standard chat
curl -X POST http://localhost:8765/api/chat \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"problem": "How to improve team productivity?"}'

# SSE streaming (decompose → activate → delta → done)
curl -X POST http://localhost:8765/api/chat/stream \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"problem": "Analyze our growth bottleneck"}'

# Memory search
curl -X POST http://localhost:8765/api/memory/search \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "growth strategy", "top_k": 10}'

Set SOMA_API_KEY env var to enable authentication. Leave unset for local development.

LangChain Tool

from soma.langchain_tool import create_soma_tool
from soma.agent import SOMA_Agent
from soma.config import SOMAConfig, load_config

agent = SOMA_Agent(SOMAConfig(framework=load_config()))
tool = create_soma_tool(agent)
result = tool.run("Analyze this problem...")

AI Coding Agent Integration (Claude Code / VS Code / JetBrains)

SOMA runs alongside AI coding tools as a persistent wisdom backend — it learns from every debug session, code review, and architectural decision.

# 1. Start SOMA server (once)
SOMA_API_KEY=dev-key python dash/server.py

Claude Code (Agent SDK) — use as a custom MCP server or REST tool:

# In your custom Claude Agent tool — persist insights across sessions
import requests
requests.post("http://localhost:8765/api/memory/remember",
    headers={"X-API-Key": "dev-key"},
    json={"content": "Bug: N+1 query in OrderService.getOrders, root cause: missing @BatchSize on items relation, fix: add Hibernate batch annotation + integration test", "importance": 0.9})

VS Code Extension — invoke via sidebar or command palette with a thin HTTP client wrapper.

Any IDE / CLI tool — just curl the REST API. No SDK required.

# Record a debug finding
curl -s -X POST http://localhost:8765/api/memory/remember \
  -H "X-API-Key: dev-key" -H "Content-Type: application/json" \
  -d '{"content":"Race condition in WebSocket handler: concurrent map writes on client.buf, root cause: missing mutex on write path, fix: sync.RWMutex around buffer ops","importance":0.9}'

# Recall relevant knowledge before starting a new task
curl -s -X POST http://localhost:8765/api/memory/search \
  -H "X-API-Key: dev-key" -H "Content-Type: application/json" \
  -d '{"query":"concurrency websocket golang","top_k":5}'

Real-World Impact

SOMA has been used in production across two distinct codebases — a Go-based CLI agent and a Python data platform — with the following results:

• Bug reoccurrence dropped significantly. When a bug fix is recorded as a SOMA memory (root cause + fix pattern), later sessions on the same codebase automatically retrieve it. Developers no longer re-debug the same class of issues across sprints.
• Architectural decisions became searchable. Each trade-off ("chose SQLite WAL over multi-worker for simplicity") is persisted with rationale context. Six months later, new team members can query "why single worker?" and get the original reasoning — not folklore.
• Cross-project knowledge transfer worked. A concurrency pattern learned in one codebase (the Go project) activated during debugging in the other (the Python project), because SOMA's semantic search matched "race condition" across language boundaries.
• Zero adoption friction. The Python project integrated via pip install soma-wisdom + 3 lines of code. The Go project integrated via REST API with a thin HTTP client (~50 lines). Neither required schema design, vector database setup, or infrastructure changes.
• Evolution is automatic. After ~50 sessions, SOMA's auto-weighting surfaced that "Inversion" (thinking backwards from failure) was consistently the most useful lens for debugging tasks, while "Analogical Reasoning" shined during architecture discussions. The framework self-tuned — no manual knob-twisting needed.

Benchmarks

SOMA v0.2.0-alpha on commodity CPU (2026-04-26):

Metric	Score	Notes
Semantic Recall	100%	10/10 paraphrased queries correctly recalled
Query Latency	5.4ms	ONNX-accelerated (fastembed), 17× faster than v0.1.0
Insert Latency	0.1ms	With SHA256 dedup + vector encoding
Dedup Rate	100%	Content-hash based deduplication
Decomposition Coverage	100%	10/10 question types correctly decomposed
Thinking Diversity	0.596	Entropy across 7 thinking laws
Synthesis Gain	+45%	Answer depth vs. bare LLM baseline

Overall Scores

Dimension	Score	Weight
Memory	97	35%
Wisdom	85	35%
Evolution	86	30%
Overall	89	—

Competitive Landscape

System	Semantic Recall	Query Latency	Dedup	Reasoning	Evolution
SOMA	100%	5.4ms	✓	Framework-based	✓
Mem0	92%	15ms	✓	—	—
MemPalace	96%	8ms	✓	—	—
Letta (MemGPT)	88%	20ms	✓	—	—
Zep	90%	30ms	✓	—	—

SOMA is the only system that combines memory storage, a reasoning framework, and evolutionary self-optimization.

Development

git clone https://github.com/soma-project/soma-core.git
cd soma-core
pip install -e ".[dev]"

pytest -v --cov=soma --cov-report=term    # 196 tests, ~97% coverage

python -m soma                              # quickstart verification

python dash/server.py                       # API server (http://localhost:8765)

Project Structure

soma-core/
├── soma/                  # Core library
│   ├── __init__.py        # SOMA facade (zero-config entry)
│   ├── __main__.py        # python -m soma quickstart
│   ├── agent.py           # SOMA_Agent: pipeline orchestrator
│   ├── engine.py          # WisdomEngine: problem decomposition
│   ├── hub.py             # ActivationHub: bidirectional activation
│   ├── evolve.py          # MetaEvolver: reflection + auto-evolution
│   ├── embedder.py        # SOMAEmbedder: fastembed + ONNX encoding
│   ├── vector_store.py    # NumpyVectorIndex: faiss ANN search
│   ├── config.py          # Pydantic configuration models
│   ├── base.py            # Data models (Focus, MemoryUnit, etc.)
│   ├── abc.py             # Abstract base classes
│   ├── langchain_tool.py  # LangChain BaseTool wrapper
│   ├── law_discovery.py   # Autonomous law discovery from clusters
│   ├── plugin.py          # Entry-points plugin auto-discovery
│   ├── analytics.py       # Usage analytics & benchmark storage
│   ├── benchmarks.py      # 3D benchmark engine (memory/wisdom/evolution)
│   ├── wisdom_laws.yaml   # Default thinking framework (bundled)
│   └── memory/
│       ├── core.py        # MemoryCore: unified memory facade
│       ├── episodic.py    # EpisodicStore: SQLite + vector BLOB
│       ├── semantic.py    # SemanticStore: knowledge triples
│       └── skill.py       # SkillStore: learned patterns
├── dash/                  # Dashboard & API server
│   ├── server.py          # FastAPI (REST + SSE streaming + auth)
│   ├── providers.py       # LLM provider manager
│   └── frontend/          # Vue 3 dashboard UI (i18n: EN/ZH)
├── docs/                  # Documentation (EN + ZH bilingual)
├── tests/                 # 196 tests, ~97% coverage
├── examples/              # Usage examples
└── pyproject.toml         # Build config

Citation

@software{soma2025,
  title        = {SOMA: Somatic Wisdom Architecture},
  author       = {SOMA Project Team},
  year         = {2025},
  url          = {https://github.com/soma-project/soma-core},
  note         = {Apache 2.0},
}

License

Apache License 2.0. See LICENSE.

---

_{🧠 五分钟接入，给你的 Agent 一个会思考的灵魂}