Put reviewed engineering knowledge in your agents’ path.

01 · Quickstart

Run Honemill locally

The current preview runs from the repository. You need Docker with Compose, PostgreSQL’s psql, Node.js 22+, and npm.

git clone https://github.com/samctur/honemill.git
cd honemill
git switch feat/phase-1-mvp
cp .env.example .env

docker compose --env-file .env -f docker/compose.yml up -d --wait
set -a && source .env && set +a
./db/migrate.sh

cd server
npm ci
npm run build
npm link

export HONEMILL_ACTOR="you@example.com"
honemill repo register --repo my-repo --display-name "My repository"

02 · First successful workflow

Propose, review, then recall

New knowledge items land in an inbox. A human reviews a specific, immutable memory revision before it becomes normal recall material. The memory command remains the stable implementation vocabulary.

honemill memory store \
  --repo my-repo \
  --kind convention \
  --summary "Run targeted tests before the full suite" \
  --body "Use the package test script with the changed test path first." \
  --source-kind manual

honemill memory inbox --repo my-repo

# Copy memoryId and revisionId from the inbox response.
honemill memory review <memory-id> \
  --revision <revision-id> \
  --promote

honemill memory search \
  --repo my-repo \
  --query "targeted tests"

Use --kind convention|decision|gotcha and --visibility repository|team. Repository is the safe default. Team-visible canon can cross repositories only inside the same Honemill database trust boundary.

03 · Existing documentation

Bootstrap from sources you already trust

Source repositories own their underlying documentation. Honemill owns the reviewed, agent-consumable projection: its scope, recall eligibility, delivery history, and evidence. Import explicitly selected, Git-tracked Markdown into the inbox:

# Preview heading-sized candidates without writing.
honemill memory import \
  --repo my-repo \
  --dry-run \
  AGENTS.md docs/architecture.md

# Import still writes only to the human review inbox.
honemill memory import \
  --repo my-repo \
  AGENTS.md docs/architecture.md

Each candidate retains repository, path, commit, heading, and digest provenance. Repeating unchanged content is a no-op; changed content creates a new candidate and never silently replaces canon. Honemill does not crawl repositories or continuously synchronize documentation.

04 · Agent access

Expose the safe MCP surface

Add the stdio server to an MCP-capable client. The exact client configuration varies, but the server entry is the same:

{
  "mcpServers": {
    "honemill": {
      "command": "honemill-mcp"
    }
  }
}

Start the client from an environment that already provides DATABASE_URL and HONEMILL_ACTOR. The server resolves repository identity from the request or the current working directory.

05 · Repeatable work

Declare loops; keep your existing runner

Honemill is a registry and evidence layer. GitHub Actions, cron, or a developer still invokes the coding agent. Commit a manifest in the consumer repository:

schemaVersion: honemill.loop-manifest/v0alpha1
loops:
  - key: pr-review
    owner: engineering
    procedureRef: git:procedures/pr-review.md@abc123
    timeoutSeconds: 900
    recall:
      tags: [convention, decision, gotcha]
      topK: 5
      threshold: 0.1
      queryTemplate: "{{repoKey}} {{changedPaths}}"

honemill loop sync --repo my-repo

# Thin pilot adapter; HONEMILL_AGENT_CMD defaults to "codex exec".
export HONEMILL_AGENT_CMD="codex exec"
node scripts/honemill-run-loop.mjs \
  --repo my-repo \
  --loop pr-review \
  --invocation "$CI_RUN_ID" \
  --changed-file src/example.ts

Prepare records the active manifest, recall policy, attempt, and exact injected revisions atomically. The adapter sends only bounded recall Markdown to the external agent, then records its exit outcome. Honemill does not retain the prompt, transcript, patch, or product data.

In Phase 1, recall tags are the supported knowledge kinds—convention, decision, and gotcha. They filter eligible canon before keyword ranking; they are not a free-form taxonomy.

honemill run prepare \
  --repo my-repo --loop pr-review \
  --invocation <stable-id> --attempt 1

honemill run finish <run-id> \
  --repo my-repo --outcome success

honemill run verdict <run-id> good \
  --repo my-repo --note "Caught a real regression"

honemill report flywheel --repo my-repo

06 · Reference

Command surface

Run honemill --help for required flags. Write and telemetry commands accept --actor and --idempotency-key; otherwise the CLI uses HONEMILL_ACTOR and generates a key.

07 · Mental model

What the evidence means

08 · Preview limits

What is not here yet

• No published package or hosted control plane.
• No built-in scheduler or agent execution.
• No dashboard, automated eval runner, or causal claims.
• No embedding provider; Phase 1 search is keyword/trigram.
• No automatic documentation synchronization or broad Notion, Confluence, Slack, or chat-history connectors.
• No separate knowledge owner, explicit supersession workflow, or applicability beyond the Phase 1 scope baseline yet.
• No general duplicate/conflict detection beyond unchanged-source import idempotency; deterministic warnings come before semantic detection.
• Phase 1 implementation is complete; real two-week dogfood acceptance is still pending.

09 · Recovery

Common checks

The CLI says DATABASE_URL is required.

Source the root .env, or provide the connection string through your shell or secret manager.

A write says an actor is required.

Set HONEMILL_ACTOR to the human or automation identity responsible for the action.

Search returns no reviewed guidance.

Confirm the candidate was promoted, its visibility includes this repository, and try --method trigram for approximate matching.

The agent ran, but finish could not reach Postgres.

Preserve the emitted outbox JSON, restore connectivity, then run honemill run reconcile <envelope.json>.