wehub-resource-sync
6c9c7fe7f3
CI / integration tests (3.13) (push) Failing after 1s
Commit lint / pull request title (push) Has been skipped
Docs / links (push) Failing after 1s
CI / unit tests (3.13) (push) Failing after 1s
CI / lint (push) Failing after 1s
CI / integration tests (push) Failing after 1s
CI / package build (push) Failing after 1s
Commit lint / commit messages (push) Failing after 1s
CI / unit tests (push) Failing after 1s
90 lines
3.9 KiB
Markdown
90 lines
3.9 KiB
Markdown
# 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),
|
|
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](https://github.com/mem0ai/mem0) | API-first memory service | mem0 stores in vector DB; we store in md files |
|
|
| [Letta](https://github.com/letta-ai/letta) | Agent OS w/ Core/Recall/Archival | Letta uses Postgres; we use markdown filesystem |
|
|
| [MemOS](https://github.com/MemTensor/MemOS) | Multi-classification memory | MemOS targets enterprise; we target lightweight (single-user / small team) |
|
|
| [memsearch](https://github.com/zilliztech/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.
|