omnity-mindos 0.5.0

Portable Digital Soul Protocol — your AI knows you, everywhere.

omnity-mindos

Portable Digital Soul Protocol -- your AI knows you, everywhere.

Install once, and every AI -- Claude, ChatGPT, Cursor, Gemini, local models -- remembers who you are, what you know, and how you think. Across devices. Forever.

Install

pip install omnity-mindos                       # core (just pyyaml)
pip install "omnity-mindos[llm]"                # + LLM-powered commit (openai)
pip install "omnity-mindos[anthropic]"          # + native Anthropic support
pip install "omnity-mindos[all]"                # + semantic vector search + all LLMs

Requires Python 3.9+.

Quick Start

# Create your soul (interactive, 5 questions)
mindos quickstart

# Teach it something
mindos commit "user: I'm a Python developer working on distributed systems"

# See what it knows
mindos status
mindos recall "Python"

# Start the server
mindos serve

Python API

from mindos import Mindos

soul = Mindos.load()                              # loads from ~/.mindos/
context = soul.hydrate(context="travel planning")  # assemble identity + relevant memories
result = soul.commit("user: I love hiking\nassistant: Great!", source="myapp")
memories = soul.recall("hiking", top_k=5)

# Generate a portable persona for any platform
ome = soul.export_ome(context="hiking")

MCP (Claude Desktop / Cursor)

{
  "mcpServers": {
    "mindos": {
      "command": "mindos",
      "args": ["serve", "--mcp"]
    }
  }
}

MCP tools: mindos_hydrate, mindos_commit, mindos_recall, mindos_forget, mindos_reflect, mindos_ome, mindos_sync.

HTTP API

mindos serve

curl localhost:3456/api/hydrate -d '{"context": "coding"}'
curl localhost:3456/api/commit  -d '{"conversation": "user: I learned Rust today", "source": "api"}'
curl localhost:3456/api/recall  -d '{"query": "Rust"}'
curl localhost:3456/api/status

API Overview

Class / Module	What it does
Mindos	The main facade. Provides hydrate(), commit(), recall(), forget(), reflect(), export_ome(), and sync(). Load it once with Mindos.load() and use it from any code.
LayerRouter	Dispatches requests to the cheapest brain layer (L0-L4) that can handle them. L0 (memory retrieval) is near-zero cost; L3 (deep reasoning) is on-demand.
MemoryStore	SQLite-backed storage with FTS5 full-text search, content-hash dedup, forgetting curve, and a sync journal for cross-device replication.
ModelRouter	Selects the best available LLM provider (DeepSeek, OpenAI, Anthropic, Ollama) per task. Automatic fallback chain: if provider A fails (timeout/error), tries provider B, then C. Falls back to rule-based extraction when no LLM is configured.

Zero-Config Setup (v0.5.0+)

from mindos.config import MindosConfig

# Auto-detect from environment variables (DEEPSEEK_API_KEY, OPENAI_API_KEY, etc.)
cfg = MindosConfig.from_env()

# Or configure programmatically — no YAML file needed
cfg = MindosConfig.from_dict({
    "models": [
        {"name": "deepseek", "type": "openai_compatible",
         "base_url": "https://api.deepseek.com",
         "api_key_env": "DEEPSEEK_API_KEY",
         "model": "deepseek-chat", "priority": 1, "for": ["chat", "reasoning"]},
        {"name": "ollama", "type": "ollama",
         "model": "qwen3.5:14b", "priority": 2, "for": []},  # catch-all fallback
    ],
})

Robustness: All LLM calls have a 30s timeout (configurable) and automatic provider failover. If DeepSeek is down, your app keeps working via the next provider in the chain.

Five-Layer Brain

Layer	Analogy	What it does	Cost
L0	Hippocampus	Memory retrieval -- FTS5 search, vector index, forgetting curve	~0
L1	Brainstem	Instinct -- hydrate assembly, emotion state, request routing	~0
L2	Cortex	Understanding -- LLM commit digestion, fact extraction	Low
L3	Prefrontal	Decision -- deep reasoning, planning, conflict resolution	On demand
L4	Self (DMN)	Identity -- reflection loop, drift detection, value alignment	Async

Cross-Device Sync

# Start a Sync Hub on your VPS
mindos serve --sync --port 3457

# On each device
export MINDOS_SYNC_URL=http://your-vps:3457
mindos sync

Every mutation is recorded in a local journal. The Hub relays events between devices but never stores your data.

Privacy

• All data lives locally in ~/.mindos/ (SQLite)
• No cloud, no accounts, no telemetry
• mindos forget "pattern" does GDPR hard delete
• Optional Bearer token auth via MINDOS_AUTH_TOKEN

Part of Omnity

SOAP            spatial protocol for 3D environments
  Mindos        <-- you are here
    Ome           individual AI agent (persona, skills, growth)
      Maxim         multi-agent society + economy
        OmeTown       the integrated world

pip install omnity-soap omnity-mindos omnity-ome omnity-maxim

License

Apache-2.0