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.
83 lines
3.7 KiB
Markdown
83 lines
3.7 KiB
Markdown
# EverOS — md-first Memory Extraction Framework
|
|
|
|
This is a Python framework for md-first memory extraction (lightweight; single-user or small-team).
|
|
|
|
## Quick commands
|
|
|
|
```bash
|
|
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](docs/architecture.md).
|
|
|
|
## Engineering practices
|
|
|
|
- **Coding rules** auto-loaded from [.claude/rules/](.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/](.claude/skills/) — `/commit`, `/new-branch`, `/pr`
|
|
- **Project-level decisions** in [docs/](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`.
|
|
|
|
Engineering infrastructure overview: [docs/engineering.md](docs/engineering.md).
|
|
|
|
## Branch strategy
|
|
|
|
`master` = released stable (hidden); `dev` = integration; `feat/* fix/*` → dev; `hotfix/*` → master + dev (sync).
|
|
|
|
See [docs/engineering.md](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](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`](https://github.com/EverMind-AI/EverAlgo) library, consumed here as the `everalgo-*` PyPI packages.
|
|
|
|
## Where things go
|
|
|
|
| Want to... | Look at |
|
|
|---|---|
|
|
| Understand architecture | [docs/architecture.md](docs/architecture.md) |
|
|
| Understand storage choice | [docs/architecture.md](docs/architecture.md) (storage section) |
|
|
| Engineering tooling overview | [docs/engineering.md](docs/engineering.md) |
|
|
| Add a new module | [.claude/rules/init-py-and-reexport.md](.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` |
|