chore: initialize EverOS 1.0.0
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.
This commit is contained in:
35
.claude/rules/module-docstring.md
Normal file
35
.claude/rules/module-docstring.md
Normal file
@ -0,0 +1,35 @@
|
||||
---
|
||||
paths:
|
||||
- "src/everos/infra/**/*.py"
|
||||
- "src/everos/memory/**/*.py"
|
||||
- "src/everos/service/**/*.py"
|
||||
- "src/everos/component/**/*.py"
|
||||
- "src/everos/core/**/*.py"
|
||||
---
|
||||
|
||||
# Module docstring rule
|
||||
|
||||
Every non-trivial module in the domain/infra layers opens with a docstring that
|
||||
explains **intent and contract**, not just a one-line label.
|
||||
|
||||
A good module docstring states:
|
||||
|
||||
- **What** the module is responsible for (one sentence).
|
||||
- **The load-bearing invariants** — the rules a reader must know to change it
|
||||
safely (partition keys, what is/isn't written, defaults, ignored flags).
|
||||
- **External usage** when the module is a package facade (a short import example).
|
||||
|
||||
Example (abbreviated, from `memory/search/manager.py`):
|
||||
|
||||
```python
|
||||
"""SearchManager — top-level orchestrator for POST /api/v1/memory/search.
|
||||
|
||||
Hard partition by owner_type: user → episodes (+ profiles), agent →
|
||||
agent_cases + agent_skills. The manager never writes to storage; it only
|
||||
reads LanceDB + markdown.
|
||||
"""
|
||||
```
|
||||
|
||||
Prefer prose that would save the next engineer a debugging session over
|
||||
boilerplate. If a module is genuinely trivial (a 3-line constant), a one-liner
|
||||
is fine — but most modules here are not.
|
||||
Reference in New Issue
Block a user