AGENTS.md · basicmachines-co/basic-memory

Sections

1. Project Overview
2. CODEBASE DEVELOPMENT
3. BASIC MEMORY PRODUCT USAGE

First lines (shown under the repo's AGPL-3.0 license)

# AGENTS.md - Basic Memory Project Guide

## Project Overview

Basic Memory is a local-first knowledge management system built on the Model Context Protocol (MCP). It enables
bidirectional communication between LLMs (like Claude) and markdown files, creating a personal knowledge graph that can
be traversed using links between documents.

## CODEBASE DEVELOPMENT

### Project information

See the [README.md](README.md) file for a project overview.

### Build and Test Commands

- Install: `just install` or `pip install -e ".[dev]"`
- Run all tests (SQLite + Postgres): `just test`
- Run all tests against SQLite: `just test-sqlite`
- Run all tests against Postgres: `just test-postgres` (uses testcontainers)
- Run unit tests (SQLite): `just test-unit-sqlite`
- Run unit tests (Postgres): `just test-unit-postgres`
- Run integration tests (SQLite): `just test-int-sqlite`
- Run integration tests (Postgres): `just test-int-postgres`
- Run impacted tests: `just fast-test` or `just testmon` (pytest-testmon; only tests affected by changed code)
- Run MCP smoke test: `just test-smoke`
- Fast static check: `just fast-check` (fix, format, typecheck)
- Fast test loop: `just fast-test` (pytest-testmon impacted tests)
- Local consistency check: `just doctor`
- Run all consolidated agent package checks: `just package-check`
- Run Claude Code plugin checks: `just package-check-claude-code`
- Run shared skills checks: `just package-check-skills`
- Run Hermes plugin checks: `just package-check-hermes`
- Run OpenClaw plugin checks: `just package-check-openclaw`
- Run host-native agent harness checks: `just agent-harness-check`
- Generate HTML coverage: `just coverage`
- Single test: `pytest tests/path/to/test_file.py::test_function_name`
- Run benchmarks: `pytest test-int/test_sync_performance_benchmark.py -v -m "benchmark and not slow"`
- Lint: `just lint` or `ruff check . --fix`
- Type check: `just typecheck` or `uv run ty check src tests test-int`
- Type check (pyright): `just typecheck-pyright` or `uv run pyright`
- Format: `just format` or `uv run ruff format .`
- Run all static code checks: `just check` (runs lint, format, typecheck)
- Create db migration: `just migration "Your migration message"`
- Run development MCP Inspector: `just run-inspector`

**Note:** Project requires Python 3.12+ (uses type parameter syntax and `type` aliases introduced in 3.12)

**Postgres Testing:** Uses [testcontainers](https://testcontainers-python.readthedocs.io/) which automatically spins up a Postgres instance in Docker. No manual database setup required - just have Docker running.

**Doctor Note:** `just doctor` runs with a temporary HOME/config so it won't touch your local Basic Memory settings. It leaves temp dirs in `/tmp` (safe to ignore or remove).

**Testmon Note:** When no files have changed, `just testmon` may collect 0 tests. That's expected and means no impacted tests were detected.

### Code/Test/Verify Loop (fast path)

1) **Code:** make changes.
2) **Check:** `just fast-check` (fix, format, typecheck; no tests).
3) **Test:** `just fast-test` for pytest-testmon impacted tests, or a targeted `uv run pytest ...` command.
4) **Verify:** `just doctor` (end-to-end file ↔ DB loop in a temp project).
5) **Package verify:** `just package-check` when changes touch `plugins/`, `skills/`, `integrations/`, package metadata, or release wiring.
6) **Full gate (when needed):** `just test` for SQLite + Postgres.

Run `just test-smoke` when you specifically need the MCP smoke flow.

If testmon is “cold,” the first run may be long. Subsequent runs get much faster.

### Consolidated Agent Package Checks

The monorepo ships several host-native packages alongside the Python core. Use the root justfile as the canonical entry point:

- `just package-check` — validates every copied package and generated bundle path.
- `just package-check-claude-code` — validates the root and plugin-local Claude marketplace manifests, the SessionStart/PreCompact hooks, the bundled output style, and the seed schemas, then runs `claude plugin validate . --strict`.
- `just package-check-skills` — validates every top-level `skills/memory-*/SKILL.md` frontmatter block.
- `just package-check-hermes` — validates `integrations/hermes/plugin.yaml`, the Hermes provider entrypoint, bundled skill, and runs the hermetic unit suite.
- `just package-check-openclaw` — runs the OpenClaw package install, copies top-level skills into the generated bundle, typechecks, lints, builds `dist/`, runs Bun tests, and performs `npm pack --dry-run`.
- `just agent-harness-check` — checks the host-specific harnesses without the shared markdown-only skills target.

Package-local justfiles live in `plugins/claude-code/`, `skills/`, `integrations/hermes/`, and `integrations/openclaw/`. Prefer the root targets for PR verification so command names stay stable as package internals evolve.

### PR CI Gate

Before opening or updating a PR, run the checks that mirror the common required CI failures:

- Run `just typecheck` in addition to targeted `ruff` and `pytest` commands when tests were added or changed.
- Sign commits with `git commit -s` so DCO passes. If a PR branch already has unsigned commits, rewrite the branch with signed-off commits before asking for review.
- Use a semantic PR title accepted by `.github/workflows/pr-title.yml`: `type(scope): summary`.
- Use one of the allowed scopes: `core`, `cli`, `api`, `mcp`, `sync`, `ui`, `ci`, `deps`, `installer`, `plugins`, `skills`, `integrations`.
- Use one of the allowed types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`. Example: `fix(cli): propagate cloud workspace routing`.

### Test Structure

- `tests/` - Unit tests for individual components (mocked, fast)
- `test-int/` - Integration tests for real-world scenarios (no mocks, realistic)
- Both directories are covered by unified coverage reporting
- Benchmark tests in `test-int/` are marked with `@pytest.mark.benchmark`
- Slow tests are marked with `@pytest.mark.slow`
- Smoke tests are marked with `@pytest.mark.smoke`

### Code Style Guidelines

- Line length: 100 characters max
- Python 3.12+ with full type annotations (uses type parameters and type aliases)
- Format with ruff (consistent styling)
- Import order: standard lib, third-party, local imports
- Naming: snake_case for functions/variables, PascalCase for classes
- Prefer async patterns with SQLAlchemy 2.0
- Use Pydantic v2 for data validation and schemas
- CLI uses Typer for command structure
- API uses FastAPI for endpoints
- Follow the repository pattern for data access
- Tools communicate to api routers via the httpx ASGI client (in process)

### Programming Style

See [docs/ENGINEERING_STYLE.md](docs/ENGINEERING_STYLE.md) for the fuller house style and
[docs/DOMAIN_MODEL.md](docs/DOMAIN_MODEL.md) for product language, ownership, identity, and
source-of-truth rules. The short version for agents:

For nontrivial Python writing, refactoring, or review, read and follow
[`.agents/skills/pythonic-code/SKILL.md`](.agents/skills/pythonic-code/SKILL.md) in full. Use
the skill's Write, Refactor, or Review mode that matches the task. GitHub coding and review
agents must apply this skill before changing or evaluating Python code.

- Prefer type-safe, explicit designs over object-heavy indirection. Use Python 3.12 `type`
  aliases, full annotations, and narrow `Protocol`s when a caller only needs a capability.
- Prefer functions and typed values before classes, and concrete classes before abstract base
  classes. Treat private-helper sprawl as a prompt to simplify the data flow.
- Use dataclasses for internal value objects and operation results; use Pydantic v2 at API,
  CLI, MCP, and persistence boundaries where validation and serialization matter.
- Keep async boundaries obvious. Resource-owning code should use context managers, propagate
  cancellation, and avoid hidden background work unless the lifecycle is explicit.
- Fail fast. Do not add silent fallback logic, broad exception swallowing, speculative
  `getattr`, or casts that hide an unclear model shape.
- Keep control flow simple and local. Push branching decisions up, keep leaf helpers focused,
  and name values after the domain concept they carry.
- Use evidence-first testing. Add or update meaningful regression tests for bugs and risky
  behavior, prefer real code paths over mocks, and run the narrowest command that proves the
  change before widening verification.
- Comments should explain why a branch, invariant, or constraint exists. Avoid comments that
  merely narrate obvious code.

### Code Change Guidelines

- **Full file read before edits**: Before editing any file, read it in full first to ensure complete context; partial reads lead to corrupted edits
- **Minimize diffs**: Prefer the smallest change that satisfies the request. Avoid unrelated refactors or style rewrites unless necessary for correctness
- **House style is canonical**: Follow the Programming Style section above for type-safe,
  fail-fast code; do not hide unclear models with speculative attributes, broad exception
  handling, casts, or unapproved fallback logic
- **No guessing**: Do not say "The issue is..." before you actually know what the issue is. Investigate first.

### Consistency Model — Review Expectations

Basic Memory separates canonical state from derived state, and reviews (human or automated)
must hold them to different standards:

- **Canonical state** — the markdown bytes of a note (on disk and as accepted
  `note_content`). Writes are guarded: CAS on `db_version`, generation fences,
  checksum-guarded file operations. Corrupting, wrongly rewriting, or wrongly deleting note
  content is always a real finding, in every code path — materialization writes canonical