ouroboros-memory 1.0.0

Lifelong, contradiction-aware, curiosity-driven memory infrastructure for large language models. Local-first, LLM-agnostic, symbolic.

Ouroboros Memory

"The LLM is the voice. Ouroboros is the mind."

Symbolic, contradiction-aware, lifelong memory infrastructure for large language models.

Ouroboros Memory is a production-ready local-first system that brings persistent, coherent, auditable memory to any LLM. Unlike embeddings-based approaches, it uses transparent symbolic knowledge graphs that detect contradictions, infer missing facts, and organize autonomously—without cloud lock-in or GPU requirements.

---

The Problem

Current LLMs suffer from three critical memory failures:

Problem	Impact
No persistent memory	Each conversation starts blank. Context windows can't hold real history.
No contradiction detection	Conflicting information silently overwrites; coherence degrades over time.
Cloud lock-in	Embeddings/vectors require expensive APIs; local alternatives are unauditable.

Ouroboros solves all three: persistent symbolic memory, contradiction detection, full auditability, runs on consumer hardware.

---

Key Features

✨ Symbolic Knowledge Graph

• Transparent (subject, relation, object) triples with confidence weights
• No opaque embeddings—every fact is human-readable and auditable
• Contradictions detected and flagged, never silently blended

🧠 Curiosity-Driven Autonomous Learning

• Automatic tension detection: contradictions, prediction errors, novelty, information gaps
• System autonomously formulates clarifying questions
• Self-organizing fact consolidation and reorganization

🔌 LLM-Agnostic

• Drop-in support for 6 providers: Ollama, llama.cpp, vLLM, OpenAI, Anthropic, Google Gemini
• Switch providers without losing a single memory
• Identical API across all backends

💻 Local-First

• Runs on laptops and consumer hardware
• No GPU required for the memory layer
• Optional local LLM support (Ollama, llama.cpp) for fully offline operation

🔐 Privacy-Respecting

• Optional 5-level privacy bridge (PII tokenization, synthetic noise injection, cloud-disable mode)
• Powered by DigiKabaz
• All privacy layers are transparent and configurable

📊 Production Ready

• 88.79% test coverage (85+ passing tests across core, llm, api, cli, storage, privacy)
• Strict code quality: ruff linting + mypy --strict type checking
• Proven scalability: 1M-fact benchmarks with constant throughput (29,469 facts/sec)
• Paper-conformant: 28 architecture claims validated against empirical data

---

30-Second Example

from ouroboros import OuroborosMind

# Create a mind (first-run wizard writes ~/.ouroboros/config.yaml)
mind = OuroborosMind()

# Add a fact
mind.chat("My name is Tony. I like dark mode.")
# → "Noted, Tony. I have crystallized your preference for dark mode."

# Switch LLM provider (memory transfers instantly)
mind.switch_llm("openai", "gpt-4o")

# Query the memory
mind.chat("What do I like?")
# → "Based on my memory, you enjoy dark mode, Tony."

# Inspect what was stored
print(mind.crystal.facts)
# → [Fact(subject='Tony', relation='has_name', object='Tony', confidence=1.0),
#     Fact(subject='Tony', relation='prefers', object='dark mode', confidence=0.95)]

---

Installation

PyPI (Recommended)

pip install ouroboros-memory

From Source

git clone https://github.com/Open-ouroboros/ouroboros-memory
cd ouroboros-memory
pip install -e .[dev,all]

LLM Setup

By default, Ouroboros uses Ollama with gemma3:4b-cloud. No setup needed; the app will guide you.

To use OpenAI, Anthropic, or other providers:

# Configure via interactive setup
ouroboros config

# Or edit directly
nano ~/.ouroboros/config.yaml

---

Architecture at a Glance

┌─────────────────────────────────────────────────────┐
│  LLM Agent (OpenAI · Anthropic · Ollama · etc.)    │
└────────────────┬────────────────────────────────────┘
                 │ System Prompt + Injected Facts
                 ▼
┌─────────────────────────────────────────────────────┐
│             8-Step Chat Pipeline                    │
│  Query Analysis → Crystal Ranker → Context Inject   │
│       → LLM Response → Fact Extract → Tension       │
│           Detection → Infer → Consolidate           │
└────────────────┬────────────────────────────────────┘
                 │
        ┌────────┼────────┐
        ▼        ▼        ▼
    ┌────────────────────────────────────────────────┐
    │        Ouroboros Memory Core                  │
    │  ┌─────────────────────────────────────────┐  │
    │  │  Crystal (Dual-layer Knowledge Graph)   │  │
    │  │  • 28 semantic relation types            │  │
    │  │  • Contradiction detection               │  │
    │  │  • Fact confidence tracking              │  │
    │  └─────────────────────────────────────────┘  │
    │  ┌─────────────────────────────────────────┐  │
    │  │  Resonance (Dynamic Attention Field)    │  │
    │  │  • 24→120 dimensional embedding space   │  │
    │  │  • Concept ranking and relevance        │  │
    │  │  • O(1) query performance                │  │
    │  └─────────────────────────────────────────┘  │
    │  ┌─────────────────────────────────────────┐  │
    │  │  Tension Engine (Curiosity System)      │  │
    │  │  • 7 tension types (contradictions,     │  │
    │  │    prediction errors, novelty, gaps)    │  │
    │  │  • Autonomous question formulation      │  │
    │  │  • Self-directed learning               │  │
    │  └─────────────────────────────────────────┘  │
    │  ┌─────────────────────────────────────────┐  │
    │  │  Storage Backend (PostgreSQL, SQLite)   │  │
    │  │  • Persistent fact storage              │  │
    │  │  • Scalable to millions of facts        │  │
    │  │  • ACID transactions                    │  │
    │  └─────────────────────────────────────────┘  │
    └────────────────────────────────────────────────┘

Full architectural detail: docs/architecture.md

---

Privacy & Security

Ouroboros integrates DigiKabaz, a privacy bridge with five graduated levels:

Level	Description
1 (None)	Memory sent to cloud as-is (default for local-only LLMs)
2 (Minimal)	Regex PII (email, phone, SSN) tokenized before cloud transmission
3 (Balanced, default)	Names, companies, locations, financial data, health info tokenized
4 (High)	All personal facts tokenized + synthetic noise injection
5 (Maximum)	Cloud LLMs disabled entirely; local models only

Transparent, configurable, auditable. No hidden encryption; you control exactly what leaves your device.

---

Getting Started

Basic Usage

# Start interactive mode
ouroboros chat

# Start REST API server (http://localhost:8765)
ouroboros start

# GUI dashboard
# → Open browser to http://localhost:8765 after `ouroboros start`

Python API

from ouroboros import OuroborosMind

# Initialize
mind = OuroborosMind()

# Chat and learn
response = mind.chat("Tell me about reinforcement learning.")
print(response)

# Access raw facts
for fact in mind.crystal.facts:
    print(f"{fact.subject} {fact.relation} {fact.object} [{fact.confidence}]")

# Inspect tensions (curiosity)
for tension in mind.tensions:
    print(f"Tension: {tension.type} — {tension.description}")

# Run a dream pass (self-directed learning)
mind.dream()

# Save and restore
mind.backup("my_memory.backup")
mind.restore("my_memory.backup")

REST API

# Start server
ouroboros start

# In another terminal:
curl -X POST http://localhost:8765/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "My birthday is May 15th"}'
# → {"response": "Noted. I have crystallized your birthday as May 15th.", "facts_learned": 1}

---

Examples

Seven runnable end-to-end examples in examples/:

#	Example	Purpose
1	01_minimal_chat.py	Two-turn conversation with crystallized concept inspection
2	02_switch_providers.py	One mind, three LLM providers (seamless switching)
3	03_persistence.py	Save, wipe, restore—facts survive across sessions
4	04_privacy_levels.py	Walk through all 5 privacy bridge levels
5	05_http_client.py	Drive REST API from Python with httpx
6	06_pipeline_inspection.py	Inspect each of the 8 chat pipeline steps
7	07_dream_and_stats.py	Run a dream pass and read component stats

Run an example:

python examples/01_minimal_chat.py

---

Documentation

• User Guide — Installation, configuration, CLI commands, Python API
• Architecture — Deep dive into Crystal, Resonance, Tension Engine, Parser, Ranker, Assembler
• API Reference — REST endpoints, WebSocket schema, async patterns
• Privacy Model — DigiKabaz integration, PII detection, noise injection
• PLAN.md — Development roadmap, design rationale, future research directions
• Benchmark Report — Scalability to 1M facts, latency profiles, storage efficiency

---

Testing & Development

# Install dev dependencies
pip install -e .[dev,all]

# Run full test suite (85+ tests)
pytest tests/

# Run with coverage
pytest --cov=src/ouroboros tests/

# Linting & type checking
ruff check .
mypy src/ --strict

# Benchmark scalability (up to 1M facts)
python scripts/bench_scalability_1m.py

---

Performance

Ingestion: 29,469 facts/second (constant across all scales)
Storage: 78.5 bytes/fact (1M facts = 74.9 MB)
Query Latency: 0.2ms p50 (O(1) behavior despite 1M facts)
Recall Accuracy: 87–92% (consistent across all scales)

See docs/benchmark_report.md for detailed results.

---

Contributing

Ouroboros is community-driven. We welcome:

• Bug reports — Use GitHub Issues
• Feature requests — Include reference to the research paper or design docs
• Code contributions — See CONTRIBUTING.md
• Research & papers — New relation types, tension algorithms, inference strategies

See DEVELOPMENT.md for contributor setup and git workflow.

---

License

Apache License 2.0. See LICENSE for details.

Commercial use is permitted. No warranty. Use at your own risk.

---

Citation

If you use Ouroboros Memory in research, please cite:

@software{ouroboros2024,
  title       = {Ouroboros Memory: Symbolic, Contradiction-Aware, Lifelong Memory for LLMs},
  author      = {Open-ouroboros Contributors},
  year        = {2024},
  url         = {https://github.com/Open-ouroboros/ouroboros-memory},
  note        = {v1.0.0, Apache 2.0 License}
}

---

Acknowledgments

Inspired by neuroscience, knowledge representation, and symbolic AI. Built on proven research in:

• Contradiction detection — Automated inconsistency resolution in knowledge graphs
• Curiosity-driven learning — Tension and novelty as learning drivers
• Local-first architecture — Privacy-respecting inference without cloud lock-in
• Symbolic memory — Transparent, auditable knowledge storage

---

Questions?

• Documentation: Start with User Guide
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Paper & Theory: PLAN.md

Made with ❤️ by the Ouroboros community.