Init

Agents need a stable project instruction block so they scan and write memory the same way every session. For MCP-only setups that block talks about MCP tools, not machine-memory CLI flags.

The managed section lives between HTML markers and can be replaced safely:

<!-- machine-memory:start -->
…
<!-- machine-memory:end -->

Everything outside the markers is preserved.

Public script (no CLI)

From the repository root:

macOS and Linux

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

Windows

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

This is the MCP counterpart to the CLI install script. It:

1. Creates AGENTS.md if missing, or updates the managed block in place
2. Writes the MCP backend workflow (tool names, repository slug rules, size preflight, checklist)
3. Prints the backend and a pointer at this docs section

Options

Examples:

# default ./AGENTS.md
curl -fsSL https://machine-memory.jfa.dev/init-mcp | bash

# custom path
MACHINE_MEMORY_AGENTS_MD=.agents/memory.md \
  curl -fsSL https://machine-memory.jfa.dev/init-mcp | bash

# default ./AGENTS.md
irm https://machine-memory.jfa.dev/init-mcp.ps1 | iex

# custom path
$env:MACHINE_MEMORY_AGENTS_MD = ".agents/memory.md"
irm https://machine-memory.jfa.dev/init-mcp.ps1 | iex

Requirements: on macOS/Linux the init-mcp script needs bash, base64, and python3. The Windows init-mcp.ps1 script needs PowerShell 5.1+ only (no extra dependencies).

CLI equivalent

If the CLI is installed:

machine-memory init --mcp

Same managed block as the public script. Use --local or --remote when agents should follow CLI commands instead — see init.

Exactly one of --local, --remote, or --mcp is required.

When to run it

• First time enabling MCP-only memory for a repo
• After changing the MCP workflow or tool surface you want agents to follow
• Safe to re-run: the block is replaced, not duplicated

What agents get

The MCP block tells agents to:

• Use MCP tools only, including maintenance (memory_doctor, memory_stats, memory_gc, memory_deprecate) and explicit bulk deletion (memory_delete_many)
• Pass an exact owner/name repository slug (no default); reads are loose (wrong slug returns empty, nothing lost) but writes are strict, so call list_repositories before every write when unsure
• Follow offset while has_more is true on memory_list and list_repositories; repository entries include status counts
• Scan with memory_suggest for known files; verify with memory_verify/memory_diff; maintain with memory_update via match or memory_add via upsert_match (weak matches need force: true)
• Set memory_type/certainty explicitly (memory_add defaults to convention/inferred); expires_after_days works only for status memories
• Preflight long content with memory_size; respect on-flight size rejection on writes
• Treat search results as ranked candidates, not an exhaustive list; rely on match_strength and no_strong_match rather than scores, and prefer known IDs, memory_suggest, and tags filters
• Set certainty from evidence: name the evidence kinds (user_requirement, observed_implementation, verified_mechanism, tested_behavior) and list validation_gaps; verified without evidence is rejected
• Keep durable knowledge separate from delivery status; say whether work is local, committed, pushed, or deployed in an expiring status record
• Carry over unrelated details when replacing a record (memory_diff and memory_update report dropped details), and resolve the review_candidates that updates and deprecations return
• Let the parent agent own memory writes; child agents return persistence candidates with evidence
• Scan before edits, then run the end-of-task checkpoint: classify each finding as covered, new durable knowledge, superseded, transient status, or intentionally omitted

Full tool reference: Tools.