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.7 KiB
EverOS — md-first Memory Extraction Framework
This is a Python framework for md-first memory extraction (lightweight; single-user or small-team).
Quick commands
uv sync # install deps
make lint # ruff (check + format-check) + import-linter
make format # auto-fix formatting
make test # pytest tests/unit
make integration # pytest tests/integration
make ci # full CI: lint + test + integration
Architecture
DDD 5 layers + cross-cutting:
entrypoints → service → memory → infra
↓
component / core / config
entrypoints/— cli + api (Presentation)service/— use case orchestration (memorize / retrieve / evolve / manage)memory/— domain (extract + search + cascade + prompt_slots + models)infra/— storage adapters (markdown + sqlite + lancedb)component/— injectable providers (llm / embedding / config / utils)core/— runtime base (observability / lifespan / context)config/— configuration data (Settings + default.toml)
Dependency rule: entrypoints → service → memory → infra. Single-direction, enforced by import-linter.
Detailed: docs/architecture.md.
Engineering practices
- Coding rules auto-loaded from .claude/rules/ (10 rules; the three always-loaded ones cover architecture / code-style / language-policy, the rest are path-scoped and load when Claude Code opens a matching file)
- Workflows as slash commands in .claude/skills/ —
/commit,/new-branch,/pr - Project-level decisions in docs/ (low-frequency, human-judgment-required)
- Language policy: the project targets a global audience — docs and code are English; CJK appears only in test fixtures and locale-suffixed mirrors. Scanned by
make check-cjk. - Datetime discipline: never call
datetime.now()/time.time()directly — useeveros.component.utils.datetime. Enforced bymake check-datetime.
Engineering infrastructure overview: docs/engineering.md.
Branch strategy
master = released stable (hidden); dev = integration; feat/* fix/* → dev; hotfix/* → master + dev (sync).
See docs/engineering.md for the full GitFlow Lite rationale.
Storage three-piece set
Markdown (truth) + SQLite (state) + LanceDB (vector + BM25 + scalar)
- Memory root:
~/.everos/{agents,users,knowledge}/(md files = single source of truth) - System DB:
~/.everos/.index/sqlite/system.db(state + audit + queue + metadata) - Index:
~/.everos/.index/lancedb/(rebuildable from md)
Selection rationale: docs/architecture.md.
Source layout
src layout (src/everos/<...>): standard PyPA project structure — code lives under src/ so the working tree is not on the import path until installed, preventing accidental imports of in-development modules.
Algorithm assets (prompts, extractors) live in the separate everalgo library, consumed here as the everalgo-* PyPI packages.
Where things go
| Want to... | Look at |
|---|---|
| Understand architecture | docs/architecture.md |
| Understand storage choice | docs/architecture.md (storage section) |
| Engineering tooling overview | docs/engineering.md |
| Add a new module | .claude/rules/init-py-and-reexport.md |
| Make a commit | use /commit |
| Open a branch / PR | use /new-branch / /pr |
| Run checks before pushing | make ci |