518b8eca85
md-first memory extraction framework for AI agents. Markdown is the single source of truth; SQLite holds state and LanceDB provides the rebuildable vector + BM25 + scalar index. The codebase follows a single-direction DDD layering (entrypoints -> service -> memory -> infra, with component / core / config cross-cutting) enforced by import-linter. Engineering surface: - Coding conventions in .claude/rules/ (path-scoped) and workflows in .claude/skills/ (/commit, /new-branch, /pr). - GitHub Actions CI runs make lint + test + integration; pre-commit mirrors the gates locally (ruff, hygiene hooks, gitlint commit-msg). - Commit messages follow Conventional Commits, enforced by gitlint. - make lint also enforces datetime two-zone discipline and OpenAPI drift.
3.5 KiB
EverOS — Project Overview
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)
- 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 separate library, published as the everalgo-* PyPI packages) holds the extraction algorithms (MemCell extraction, Episode generation, Profile evolution). EverOS calls everalgo via the PromptSlot interface; 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
- v2 (future) — Edge-to-cloud sync via EverMe (separate project)
Status
Alpha — v0.1.0 in active development. Core API may change before v1.0.