Metadata-Version: 2.4
Name: evaos
Version: 0.9.0
Summary: AI memory engine with identity preservation — remember everything, forget nothing
Author-email: 100Yen Org <dev@100yen.org>
License-Expression: MIT
Project-URL: Homepage, https://github.com/100yenadmin/electric-sheep
Project-URL: Repository, https://github.com/100yenadmin/electric-sheep
Project-URL: Documentation, https://github.com/100yenadmin/electric-sheep#readme
Project-URL: Issues, https://github.com/100yenadmin/electric-sheep/issues
Keywords: ai,memory,llm,identity,companion,evaos
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: tiktoken>=0.7
Requires-Dist: rapidfuzz>=3.6
Requires-Dist: numpy>=1.26
Requires-Dist: click>=8.1
Provides-Extra: llm
Requires-Dist: openai>=1.50; extra == "llm"
Requires-Dist: anthropic>=0.40; extra == "llm"
Requires-Dist: ollama>=0.4; extra == "llm"
Provides-Extra: embedding
Requires-Dist: voyageai>=0.3; extra == "embedding"
Provides-Extra: server
Requires-Dist: fastapi>=0.115; extra == "server"
Requires-Dist: uvicorn>=0.30; extra == "server"
Requires-Dist: pydantic>=2.0; extra == "server"
Requires-Dist: httpx>=0.27; extra == "server"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: vec
Requires-Dist: sqlite-vec>=0.1.0; extra == "vec"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: aiohttp>=3.9; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Provides-Extra: all
Requires-Dist: evaos[dev,embedding,llm,mcp,server,vec]; extra == "all"
Dynamic: license-file

<div align="center">

# 🐑 evaOS (Electric Sheep)

**AI memory that remembers who you are.**

[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![PyPI](https://img.shields.io/badge/pypi-evaos-orange.svg)](https://pypi.org/project/evaos/)

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

</div>

---

## 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

```bash
pip install evaos
```

With vector search (recommended):
```bash
pip install "evaos[vec]"
```

All extras (LLM providers, HTTP API, MCP server):
```bash
pip install "evaos[all]"
```

---

## 30-Second Quickstart

```bash
# 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:

```toml
[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/`](docs/) for full configuration reference and architecture deep-dives.

---

## CLI Reference

```bash
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](CONTRIBUTING.md) for dev setup, testing, and PR guidelines.

---

## License

[MIT](LICENSE) — 100Yen Org
