archmap memory

Renders the project's architecture — health score, top risk files, cycles, layer and rule violations — into a compact markdown digest an AI coding agent can read at the start of a session instead of re-exploring the codebase from scratch with a pile of Read/Glob/Grep calls. Nothing new is computed: this is the same report archmap analyze produces, condensed into prose.

Usage

archmap memory [path] [options]

Option	Default	Description
path	.	Project root to analyze
--out PATH	<path>/.archmap/memory.md	Output file path
--print	off	Print the digest to stdout instead of writing a file
--quiet	off	Suppress the confirmation line (for hooks)
--parallel / --no-parallel	on	Parallel file parsing

Cheap to call repeatedly: archmap memory goes through the same fingerprint cache archmap analyze uses, so a no-op call after an unrelated file edit is nearly instant. Writes are idempotent too — re-running with no architectural change skips the write entirely rather than touching the file's mtime (and creating a no-op git diff) just because the timestamp line changed.

Example

archmap memory .
# [ok] Wrote /home/me/my-api/.archmap/memory.md

# ArchMAP Project Memory

_Auto-generated by `archmap memory` — do not edit by hand; regenerate with `archmap memory`._
_Generated: 2026-08-12 22:57 UTC_

## Health
- Score: **78/100** (B) — Architecture is mostly healthy with manageable drift.
- Style: **modular_monolith** (confidence 0.81)
- Files: 142 | Dependencies: 389 | External packages: 23
- Cycles: 1 | God modules: 2 | Layer violations: 0 | Custom rule violations: 0

## Top risk files
- `src/core/engine.py` — risk 62 (dependents: 18, outgoing: 22; god_module, circular_dependency)
...

## For AI agents
- This file is a pre-computed snapshot — trust it over re-exploring the codebase from scratch...

Wiring it into Claude Code automatically

The point of archmap memory is that you never run it by hand — it should refresh itself as you edit, and its content should already be in context the moment a session starts. Claude Code's hooks do both — see Claude Code's own hooks documentation for the authoritative reference. Add this to your project's (or user-level) .claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "archmap memory . --print"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
        "hooks": [
          {
            "type": "command",
            "command": "archmap memory . --quiet"
          }
        ]
      }
    ]
  }
}

• SessionStart runs archmap memory --print once when a session begins; its stdout is added directly to Claude's context, so the agent starts already knowing the project's health score, risk hotspots, and violations — no tool call spent rediscovering them.
• PostToolUse (matching the file-editing tools) regenerates .archmap/memory.md after every edit, so the next session (or the next get_project_memory MCP call in this one) reflects the current state of the code, not a stale snapshot from before the change.

Check the hooks documentation for your Claude Code version — the exact event/matcher syntax has evolved, and settings.json accepts both user-level (~/.claude/settings.json) and project-level (.claude/settings.json) configuration.

Via MCP instead

If you'd rather not touch hook configuration, archmap mcp exposes the same digest as the get_project_memory tool — call it once at the start of a conversation about the project. See archmap mcp.

Should .archmap/memory.md be committed?

Either is reasonable:

• Commit it if you want teammates and their agents to benefit from the same up-to-date context, and don't mind the small diff noise on every meaningful architectural change.
• Gitignore it (.archmap/) if you'd rather treat it as a purely local, regenerable cache — the PostToolUse hook keeps it fresh locally either way.