Home

The agent harness that gives you the assistant you want — part Star Trek Computer, part J.A.R.V.I.S.

_{Works with Claude Code + Antigravity — see compatibility}

Agent M is an agentic memory implementation that combines a persistent knowledge layer with personally curated content (i.e. your own notes in markdown format) through a combination of skills, sidecars, and vectorized indexing. Imagine those workflows you saw in the movies. You're talking to your agent, "Let's open a new file for project M" and off you go. It remembers your projects and files together, can talk to you about them, and it learns and grows with you as you work. The context it builds is self-maintaining and it improves automatically as you go. No need to spend time maintaining your own knowledge graphs, and it can help you with your personal notes too, when you want it to.

Agent M has grown over time across the paired releases of agentm and crickets. The full V1→V4 evolution — what shipped, what's deferred, where the design is going — lives in Agent Memory Evolution on the toolkit side. This page is the entry point for the harness itself.

Note

This wiki documents the agentm repo for contributors. Target projects get templates/wiki/ installed instead. See ADR 0002 for why.

Get started

Once both repos are cloned and the vault folder exists, Agent M is operational.

1. Install both repos as siblings

git clone https://github.com/alexherrero/agentm.git ~/Antigravity/agentm
git clone https://github.com/alexherrero/crickets.git    ~/Antigravity/crickets

2. Point the vault at your existing Obsidian + sync setup

mkdir -p "<sync-root>/AgentMemory/personal-private/_always-load"
mkdir -p "<sync-root>/AgentMemory/projects"
mkdir -p "<sync-root>/AgentMemory/_meta"
export MEMORY_VAULT_PATH="<sync-root>/AgentMemory"

Pre-v4.1.0 vaults used personal-projects/ (renamed to projects/ in V4 #26). Existing operators run bash agentm/scripts/rename-vault-personal-projects.sh after upgrading. The resolver transparently handles both layouts.

Any sync layer works (Google Drive, Dropbox, syncthing).

3. Install the quality-gates bundle and the memory skill into your target project

bash ~/Antigravity/crickets/install.sh <target-project> --bundle quality-gates
bash ~/Antigravity/crickets/install.sh <target-project> --skill memory

The bundle lands the evaluator sub-agent + four base hooks (kill-switch, steer, commit-on-stop, evidence-tracker) in one operation.

4. Seed your always-load entries

Capture your locked conventions, coding-style rules, project invariants under <vault>/personal-private/_always-load/. One entry per concern. The first pass is co-created — you and the agent walk through it together; you approve each entry.

5. Verify

python3 ~/Antigravity/agentm/scripts/harness_memory.py recall --phase setup

Should print your always-load entries within the 4000-token budget. Empty = vault is reachable but un-seeded. Errored = MEMORY_VAULT_PATH is unset or unreadable.

📚 New here? Learn by doing.

• Tutorial 1 — Your first harness install — fresh clone to a healthy installed scratch project in ~5 minutes.

🔧 Trying to do something specific?

• How to install the harness into a project — add the scaffold to an existing repo.
• How to configure a new project on first session — detect → propose → approve → persist the per-project enablement config.
• How to refresh an installed harness — pull a newer harness version into a project that already has one.
• How to cut a release — tag, changelog, GitHub release via the ship-release skill.
• How to use auto-context in harness phases — tune MemoryVault recall budgets, save modes, and confidence thresholds for each phase.
• How to use per-project install — when to deliberately keep --scope project instead of migrating to user scope (CI runners; shared dev hosts; multi-developer dotfiles).
• How to audit the MemoryVault — run the read-only vault lint, read the report under _meta/, and apply suggested fixes by hand.
• How to find missing note links — run the read-only personal-notes link-discovery audit and add the suggested [[wikilinks]] by hand.
• How to use AgentMemory in any agent — configure any surface (Claude.ai · Gemini · ChatGPT · Antigravity) to read the vault natively (read-only) by pasting the one context payload.
• How to tune auto-orchestration — edit the toggles, thresholds, and cooldowns that drive the SessionStart briefing and the idle-time memory chain.
• How to run without a vault — operate the harness with no MemoryVault configured. (pending — Hardening I)

📖 Looking up a detail?

• Installer CLI reference — flags, prerequisites, ownership table for install.sh / install.ps1.
• Detection rules reference — the 10 built-in rules and what each attaches a rationale to.
• Project config reference — the project.json enablement-block schema.
• Migration tool reference — flag-by-flag for migrate-to-user-scope.{sh,ps1} + the 4-state matrix + .agentm-migrate-record.json schema.
• CI gates reference — what each CI workflow proves and the script behind it.
• Repo layout reference — top-level directory map and four-adapter parity table.
• Vault lint checks reference — the 9 read-only vault_lint.py checks: id / severity / what each checks / suggested-fix shape.
• Note relatedness signals reference — the two signals (TF-IDF + embedding) + thresholds notes_link_discovery.py scores on.
• AgentMemory context payload reference — the canonical paste-anywhere payload's sections (path resolution / folder map / read priority / conventions / read-only boundary).
• Auto-orchestration config reference — every config key + default (toggles / thresholds / cooldowns) and the auto-orchestration-state.json shape.
• Compatibility — supported hosts (Claude Code, Antigravity) + OS matrix + adapter contract.
• Completed features — reverse-chronological log of shipped work.

💡 Want to know why?

• Agent Memory Evolution V1→V4 — the full HLD: where Agent M started, how it grew, where it's going. The architecture, the schema, the workflows, the V4 design space.
• V3 Retrospective — what shipped across the V3 arc, what we learned, what's deferred.
• Product intent — what problem the harness solves and for whom.
• Auto-detect + auto-configure — why first-session config proposes-then-approves and why it lives in project.json.
• How the pieces fit — narrative of how phases, adapters, templates, and scripts interact.
• GitHub Projects integration — why and how the harness writes to ProjectsV2.
• Auto-orchestration — why the memory skills became a push surface, and how the briefing + idle chain + phase dispatch never nag.
• Single-repo state mode — how the harness degrades to repo-local state when no vault is reachable. (pending — Hardening I)

Architecture decisions

• ADR 0001 — Phase-gated workflow
• ADR 0002 — Documentation convention
• ADR 0003 — ProjectsV2 ownership and linking
• ADR 0004 — Diátaxis documentation spec
• ADR 0005 — Drop Codex support; three-adapter scope
• ADR 0006 — Split customizations into crickets
• ADR 0007 — Auto-context into harness phases
• ADR 0008 — Project surface split

Conventions

Page templates, filename rules, and the Diátaxis four-mode split are described in templates/wiki/README.md — the same conventions this wiki follows.