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.
1.2 KiB
1.2 KiB
paths
| paths | |||||
|---|---|---|---|---|---|
|
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):
"""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.