evaos 0.9.0

AI memory engine with identity preservation — remember everything, forget nothing

🐑 evaOS (Electric Sheep)

AI memory that remembers who you are.

Identity-preserving memory engine for AI agents.
Your agent wakes up tomorrow and still knows who it is.

---

Why evaOS?

Most AI memory systems are glorified vector stores. They dump embeddings into a database and call it "memory." The result: progressive identity drift (your agent slowly forgets who it is), junk accumulation (10,000 useless coding-session memories), and no lifecycle (no consolidation, no forgetting, no sleep).

evaOS is a cognitive memory engine grounded in memory research. It extracts claims, resolves entities, protects core identity, and runs dream cycles to consolidate and prune — just like biological memory.

---

Install

pip install evaos

With vector search (recommended):

pip install "evaos[vec]"

All extras (LLM providers, HTTP API, MCP server):

pip install "evaos[all]"

---

30-Second Quickstart

# Initialize a new memory store
evaos init

# Teach it something
evaos remember "Andrew is the founder of 100Yen Org. He lives in Bangkok."

# Ask it later
evaos recall "Where does Andrew live?"
# → Andrew lives in Bangkok. He is the founder of 100Yen Org.

That's it. Memories persist in a local SQLite database, searchable via hybrid BM25 + vector retrieval.

---

Features

🧠 5-Layer Memory Model

Layer	What It Does
Extraction	LLM-powered claim extraction with noise filtering (skips "changed line 47 of auth.py")
Entity Resolution	Fuzzy deduplication — "Andrew", "andrew", "@andrew" → same person
Reconciliation	Smart conflict resolution: ADD / UPDATE / SUPERSEDE / NOOP
Cornerstones	Immutable identity anchors that resist drift and accidental deletion
Token Budget	Assembles memory context within configurable token ceilings

🌙 Dream Cycles

Circadian engine with sleep/wake/dream phases. During idle time, evaOS consolidates memories, runs Ebbinghaus decay on low-signal noise, and calculates identity drift against cornerstone baselines.

🕸️ Brain Graph

File-watcher + auto-registration document memory graph. Index your docs, specs, and decisions — query them alongside conversational memory.

🔍 Hybrid Retrieval

BM25 full-text search + vector similarity with Reciprocal Rank Fusion. Optional agentic re-ranking for high-stakes queries.

🔌 Three Interfaces

Interface	Use Case
CLI	evaos remember, evaos recall, evaos dream
HTTP API	FastAPI REST server — evaos serve
MCP Server	Model Context Protocol for agent frameworks — evaos mcp

---

Architecture

┌─────────────────────────────────────────────────┐
│                   evaOS Engine                   │
├──────────┬──────────┬──────────┬────────────────┤
│   CLI    │ HTTP API │   MCP    │  Plugin API    │
├──────────┴──────────┴──────────┴────────────────┤
│              Retrieval Pipeline                   │
│         (BM25 + Vector + RRF + Rerank)           │
├──────────────────────────────────────────────────┤
│  Extraction │ Entity Res. │ Reconciliation       │
├──────────────────────────────────────────────────┤
│  Cornerstones │ Drift Calc │ Feedback Loop       │
├──────────────────────────────────────────────────┤
│         Circadian Engine (Dream Cycles)          │
│       Deprecation Pipeline (Ebbinghaus)          │
├──────────────────────────────────────────────────┤
│  Token Budget │ Brain Graph │ Validation Layer   │
├──────────────────────────────────────────────────┤
│          SQLite + FTS5 + sqlite-vec              │
└──────────────────────────────────────────────────┘

---

Configuration

evaOS uses a cortex.toml config file:

[cortex]
storage_backend = "sqlite"

[cortex.storage]
db_path = "evaos.db"

[cortex.extraction]
model = "haiku"              # or "gpt-4.1-nano"
noise_filter = true

[cortex.cornerstones]
max_count = 7
drift_threshold = 0.15

[cortex.circadian]
dream_interval_hours = 6
decay_curve = "ebbinghaus"

See docs/ for full configuration reference and architecture deep-dives.

---

CLI Reference

evaos init [--profile companion|coding|enterprise]
evaos remember "text"
evaos recall "query"
evaos cornerstones list
evaos cornerstones seal --label "name" --content "text"
evaos dream
evaos stats
evaos health
evaos export [--format json|sql]
evaos serve [--port 8000]
evaos mcp
evaos backup [--output path]

---

Project Structure

cortex/
├── core/               # Extraction, entity resolution, reconciliation, retrieval
├── storage/            # SQLite adapter with FTS5 + vector support
├── brain_graph/        # Document memory graph with file watching
├── circadian/          # Sleep/wake/dream cycle engine
├── deprecation/        # Ebbinghaus decay pipeline
├── identity/           # Cornerstone guardian + drift calculator
├── config/             # TOML config loading + profiles
├── api/                # FastAPI HTTP server
├── integrations/       # MCP server + plugin interface
├── cli.py              # Click-based CLI
└── types.py            # Shared dataclasses and types

---

Contributing

See CONTRIBUTING.md for dev setup, testing, and PR guidelines.

---

License

MIT — 100Yen Org