EverOS CLAUDE.md

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, /release
• 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 — use everos.component.utils.datetime. Enforced by make check-datetime.