Project memory

You decided last week to use JWT instead of sessions, and you captured why. You discovered that a third-party API rate-limits at 100 req/min unless you pass a specific header. The agent that helped you is gone — credit limit, browser tab closed, weekend break. The next agent that looks at your code has no idea those constraints exist, and cheerfully proposes the things you already ruled out.

brainclaw fixes this. Decisions, constraints, and traps live in .brainclaw/memory/, one file per item, versioned in Git. Every agent that opens the project reads them on its first context call. They survive sessions, agents, and human breaks.

# When you decide something — capture it
bclaw_create entity=decision data={
  text: "JWT for auth, not sessions. Stateless, scales horizontally.",
  outcome: "approved"
}

# When you find a trap — capture it
bclaw_create entity=trap data={
  text: "Vendor API rate-limits at 100 req/min without X-Throttle-Override header",
  severity: "high"
}

# Next session, on any agent
bclaw_context kind=memory path="src/api/"
# → returns the constraint AND the trap, ranked by relevance

Three flavours: decisions (the choices you locked in), constraints (the rules to follow), traps (the gotchas you wish you’d known). All searchable by tags and full-text, all surface automatically in the right context. See release hardening for how this changes the way teams ship.