init

Prerequisites

This tool uses Bun Secrets to safely store items in your keychain and requires the userspace to have access to it.

While this is guaranteed on Windows and macOS machines, Linux users must have a compatible libsecret keychain available on the shell session.

Usage

machine-memory init (--local|--remote|--mcp)

This command creates AGENTS.md when it does not exist, or replaces the content between the machine-memory:start and machine-memory:end markers when it already exists. Everything outside those markers is preserved.

The generated block tells future agents how to scan memory, which backend to use, and how to maintain durable project context. The selected backend is written into the block so its examples stay consistent with the command you ran.

Every backend’s block also covers memory hygiene:

• Search results are ranked candidates, not an exhaustive list. Agents judge relevance by each result’s match_strength and the response’s no_strong_match rather than by scores, prefer known IDs, file-scoped suggestions, and tag filters, and read full records before relying on them.
• Certainty follows evidence: agents record which kinds support a claim (user_requirement, observed_implementation, verified_mechanism, tested_behavior) and the remaining validation gaps. verified without evidence is rejected, and doctor lists legacy verified memories for review.
• Durable decisions and mechanisms stay separate from delivery status. An expiring status record says whether work is local, committed, pushed, or deployed.
• Updates carry over unrelated valid details, guided by the dropped report from update --dry-run and diff, and the review_candidates returned by updates and deprecations are reconciled.
• The end-of-task review starts from machine-memory checkpoint, and other repositories are addressed with --repo owner/name rather than by changing directory.
• In delegated work, the parent agent owns memory writes. Child agents return persistence candidates with evidence.
• Before the final response, agents run an end-of-task checkpoint that classifies each finding as already covered, new durable knowledge, superseded or conflicting, transient status, or intentionally omitted.

Backend selection

Exactly one flag is required:

machine-memory init --local

machine-memory init --remote

machine-memory init --mcp

For MCP-only repos without the CLI installed, use the public script instead:

curl -fsSL https://machine-memory.jfa.dev/init-mcp | bash

On Windows:

irm https://machine-memory.jfa.dev/init-mcp.ps1 | iex

Details: MCP → Init.

When to run it

Run this after changing the project’s memory workflow or backend policy. It is safe to run again: the managed block is updated in place rather than appended repeatedly.