agent-memory

agent-memory

agent-memory is a local context middleware that maintains a structured, byte-preserving Markdown memory layer for this repository. Your runtime exposes three MCP tools backed by it:

• memory.fetch_context — read; returns a budgeted Markdown pack drawn from current task state, conventions, decisions, modules, and (on query) the most relevant indexed sections.
• memory.propose_update — write; submits structured operations that the server validates, secret-scans, and either applies immediately or stages for human review.
• memory.status — health; reports file counts, pending staged proposals (with drift status), and security/git/lock posture. Call it when you want to know whether memory needs maintenance before proposing more updates.

At session start: always fetch_context with empty query

{ "name": "memory.fetch_context", "arguments": {} }

The empty-query (“bootstrap”) pack contains:

• local/current.<branch>.md — your last working notes on this branch.
• local/current.shared.md — cross-branch shared state.
• conventions.md — project conventions.
• index.md — summary of the memory layout.

Read it carefully before reading source files. It tells you what the team already decided, what footguns are documented, and where you left off.

When else to fetch_context

Trigger	Call
Topic shift mid-task (auth → billing)	fetch_context with a query naming the new topic
About to make an architectural decision	fetch_context with a query naming the area
Refactoring an unfamiliar module	fetch_context with scope: ["<module-path>"]

Do not call fetch_context on every tool call. Once at session start plus query-driven refreshes is the right cadence.

When to propose_update

Pick the intent that matches the situation. Each intent maps to a specific category of memory file and an approval policy.

Situation	intent	Routes to
Working notes on this task, branch-scoped	update_current	apply
Working notes that follow you across branches	update_shared	apply
End-of-task log of what you did	session_log	apply (path auto-rewritten to sessions/<UTC today>.md)
Hit a footgun future-you should avoid	add_pitfall	apply (when append_to_section) / stage (when rewriting)
Made a durable architectural decision	record_decision	stage
Updated facts about a module	refresh_module	stage
Discovered a team convention	update_conventions	stage
An older entry is no longer accurate	archive_stale	stage