$ show EverMind-AI/EverOS
EverOS is a local-first, markdown-based memory framework for AI agents and chat applications. It ingests conversational sessions via a FastAPI REST API, extracts structured memories (episodes, atomic facts, agent cases, skills, user profiles) using LLMs, persists them as version-controllable Markdown files, and maintains derived search indexes in LanceDB (vector + BM25) and SQLite. The system provides a rich retrieval layer with keyword, vector, hybrid (RRF), and agentic (LLM-guided multi-round) search methods, plus a knowledge wiki feature. An Offline Memory Engine (OME) runs background strategies (reflection, clustering, extraction) on cron/idle/immediate triggers, and a cascade daemon watches the Markdown filesystem to reconcile indexes. The architecture is a layered monolith (entrypoints → service → memory → infrastructure) with cross-cutting components for LLM, embedding, rerank, tokenizer, and config. It ships with a CLI (Typer), a TUI demo (Textual), and extensive integration tests. While primarily an application, it includes a benchmark harness (LoCoMo, LongMemEval, EverMemBench) and evaluation fixtures, giving it a hybrid character with a strong research-oriented testing pipeline.
The LLM identified 5 files worth highlighting for reuse:
A backend-neutral predicate DSL for building filter expressions across vector stores (LanceDB, Milvus). Provides composable primitives (all_of, any_of, eq, gt, is_null, contains, one_of) that compile to backend-specific SQL or expression syntax. Includes reserved-field enforcement and a compile_filters entry point. This is a clean, reusable pattern for any multi-backend storage system requiring dynamic query construction.
A single-function module providing sanitize_dirname() for converting free-text strings into safe filesystem directory segments. Implements CWE-22 path traversal prevention (rejects '.', '..', null bytes, and absolute paths), NFC normalization, and a configurable character whitelist. Includes a fallback mechanism for fixpoint cases. This is a self-contained, security-critical utility reusable in any project that derives filesystem paths from user or LLM-generated text.
A well-structured exception hierarchy rooted at AppError, branching into DomainError, InfrastructureError, CapabilityError, and ConfigurationError. Each branch has specific subclasses (e.g., ProviderNotConfiguredError, CascadeNotReadyError, LanceDBMigrationError). Includes error codes, HTTP status mappings, and a helper for wrapping external exceptions. This pattern is reusable in any Python application that needs typed, catchable error categories with clear separation of concerns.
The OME strategy framework provides a @offline_strategy decorator that registers background tasks with declarative triggers (Immediate, Cron, Idle), gates (Counter with inspect/dry-run), retry/dead-letter configuration, and DAG validation. Strategies are collected into a StrategyRegistry with startup-cycle detection and duplicate validation. The framework includes run records (state machine: RUNNING→SUCCESS/FAILED/DEAD_LETTER/CRASHED), partition locks for concurrency, and a testing harness with fakes. This is a reusable, production-hardened pattern for building event-driven background job systems with idempotency guarantees.
A Pydantic-based ORM layer for LanceDB tables. BaseLanceTable subclasses declare TABLE_NAME, BM25_FIELDS, PRIMARY_KEY, and schema/vector index specs co-located with the model. Provides create_table (with schema patching for nullability), FTS index lifecycle (create/recreate), vector index management (IVF_FLAT with configurable partitions/nprobes), and a touch() helper for explicit updated_at updates. Includes migration support (migrate_table_schemas) with error recovery. This is a clean, reusable pattern for any project using LanceDB as a vector store with structured metadata.