Skip to content

AGENTS.md

Latest commit

 

History

History
53 lines (46 loc) · 3.02 KB

AGENTS.md

File metadata and controls

53 lines (46 loc) · 3.02 KB
Raw

Agent instructions

This file is for coding agents that work in this repository. It gives the commands and the rules, and points to the files that hold everything else.

Commands

make verify       # the full check; run it before each commit
make integration  # the hotdata tests and the conformance suite; needs make local-up
make floor        # the offline tests at the lowest allowed dependency versions
make local-up     # start the local engine stack (Postgres, RustFS, engine)
make local-down   # stop it and delete its data
cp .env.template .env            # then fill in .env; it is ignored by git
uv run --env-file .env scripts/measure_cloud.py   # M1 to M3
uv run --env-file .env scripts/measure_local.py   # M4 to M6; needs make local-up
uv run --env-file .env scripts/measure_local.py --cloud   # M4 to M6 in the cloud

Where things are

  • docs/internal/: the notes of the owner. Git ignores this folder, so it exists only in the owner's checkout. plan.md holds the open workstream, the tasks of each phase, and its stop conditions. roadmap.md holds every phase and its status. brief.md holds the design and its reasons. local.md tells you how to run against the local stack.
  • docs/contracts.md: the record and the operations.
  • docs/guarantees.md: what a consumer can rely on, and the proof.
  • docs/architecture.md: how each operation runs on the platform.
  • CONTRIBUTING.md: the checks inside make verify and the test rules.
  • CHANGELOG.md: each change to a public surface.
  • RELEASING.md: how to publish a version to PyPI. Only the repository owner publishes.
  • src/hotmemory/: the library. tests/test_conformance.py is the conformance suite.
  • docs/benchmarks.md: the benchmark numbers and their configuration.
  • bench/: the LongMemEval-S runner, outside the package. bench/README.md gives its commands. Each run writes its result file into bench/results/, which git ignores.
  • skills/hotmemory/: the skill file for agents, one script for each memory operation, and an example document for the load script. tests/test_skill.py runs every command in the skill file.

Rules

  • Work the current GitHub issue in task order, on one branch from main.
  • Do not push, open a pull request, or post a comment until the repository owner agrees.
  • Never name a private repository, a customer, or a deployment detail in a committed file. Before each commit, search the diff for the names that you know.
  • Never write a measured number that you did not observe. Mark a claim that you read from source, and did not observe, as not observed.
  • The measurement scripts read credentials from the environment. Do not put a key, a workspace id, or a database id in a file.
  • If a change alters a behavior, update docs/contracts.md and docs/guarantees.md in the same commit.
  • If a change alters a frozen surface, add an entry to CHANGELOG.md in the same commit.