EverOS

Vision

Build an open-source Python memory framework where AI agents' long-term memory is plain Markdown files on the user's disk, not opaque rows in a hosted database.

Scope

In scope (v1):

• Local deployment for personal agents or small teams
• Conversation, workflow, agent-trace, file-knowledge → structured memory
• Hybrid retrieval (BM25 + vector + scalar filter)
• Cascade index sync (md edit → LanceDB sub-second)
• Dual-track memory (user-track / agent-track)
• Offline memory evolution (Foresight / AtomicFact / Profile / Skill), including Reflection — a consolidation strategy within the OME that merges + re-extracts related episodes
• Knowledge base (document upload, parse, CRUD, semantic search)
• CLI + HTTP API

Out of scope (v1, future v2):

• Multi-tenant / group / community deployment (10K+ users)
• End-to-cloud sync (planned for v2)
• Distributed deployment / sharding

Design philosophy

1. Markdown as Source of Truth

delete all LanceDB / SQLite files → can rebuild from md
delete any md file               → memory is gone

User trust comes from physical visibility — the user can cat / vim / grep their own memory at any time.

2. Three-piece storage with clear job boundaries

Component	Role	Does NOT do
Markdown files	Truth source — entries, frontmatter	Search (grep is degraded fallback only)
SQLite	Queue, cascade audit log, sensitive data isolation	Vector / full-text
LanceDB	Vector ANN + BM25 + scalar filter, single-query hybrid	Be the source of truth (loss = rebuild from md)

3. Algorithm-orchestration separation

everalgo (a set of separate PyPI packages — everalgo-user-memory / -agent-memory / -rank / -knowledge, plus the optional -parser extra) holds the extraction algorithms (memory-cell extraction, episode generation, profile evolution). EverOS calls everalgo's extractor functions directly — passing storage-free data in, getting structured results out; for a couple of extractors (episode and boundary detection) it can override the bundled prompt via the PromptSlot mechanism. everalgo knows nothing about storage.

This boundary lets the same algorithm power both this open-source lightweight version and other product forms.

4. DDD layered architecture

entrypoints  →  service  →  memory  →  infra
                              ↓
                        component / core / config

Strict single-direction dependency, enforced by import-linter in CI.

Why src layout (src/everos/)

• Standard PyPA project structure used when shipping to PyPI
• Avoid namespace collision with system packages named memory, infra, etc.
• Avoid accidental import of working-tree code in dev (PyPA recommendation)

Comparable projects (where EverOS differs)

Project	Position	Difference
mem0	API-first memory service	mem0 stores in vector DB; we store in md files
Letta	Agent OS w/ Core/Recall/Archival	Letta uses Postgres; we use markdown filesystem
MemOS	Multi-classification memory	MemOS targets enterprise; we target lightweight (single-user / small team)
memsearch	md-first search engine	Closest to us; we add memory extraction (not just search)

Roadmap

• v0.1 (MVP) — Phase 1 core loop: markdown + lancedb + cascade + episode extraction
• v0.2 — Full extraction pipeline (workspace / agent / knowledge), evolution framework
• v0.3 — Production hardening, full CLI, HTTP API, Obsidian demo
• v1.0 — Stable API, PyPI release, comprehensive docs
• v1.1 — Knowledge base + Reflection (offline memory consolidation)
• v2 (future) — Edge-to-cloud sync via EverMe (separate project)

Status

Latest stable release: v1.1.0 (PyPI) — the v1 API is stable.