agent-memory

name	agent-memory
description	Teaches agents how and when to use BrainRouter's memory engine (including Long-Term L1/L3, Short-Term Working Memory offloads, and Software Engineering-specific tools). Ensures the agent maintains context-awareness while proactively keeping context limits low.
hints	- Extract if the user disables or opts out of memory capture (respect this as a hard rule). - Note if the user prefers a specific recall strategy (keyword vs. hybrid). - Capture if the user requests the agent to "forget" specific information. - Note any sessions where the user explicitly asked for memory context to be surfaced. - Ensure working memory offload is triggered for payloads >1,000 tokens.

Agent Memory — Using BrainRouter Memory Tools

Overview

BrainRouter's memory engine gives you persistent, cross-session awareness of the user. Use it consistently — an agent that doesn't recall context is worse than a stateless one because it appears to ignore the user.

With the new Memory Systems, you have access to:

1. Long-Term Memory: Retrieval-Augmented Generation (RAG) based on L1/L3 database entries.
2. L2 Pre-Warming Context (SNN): Spiking Neural Network-inspired skill potentials. Invoking skills/tools charges potentials (up to 4.0), while idle turns/time apply exponential decay. Active skill hints (potential >= 0.3) are dynamically injected under <skill-prewarm> system prompt blocks.
3. Short-Term Working Memory: Active task canvases and reference-offloading to keep your prompt context clean and small during long conversations.
4. Software Engineering Tools: Structured memory types (e.g., failed attempts, debug traces, file histories, task handovers).

---

Workflow

1. Resolve and Start: Call mcp_brainrouter_resolve_session at the beginning of a turn.
2. Context Setup & Pre-Warming: Scan your system prompt for <skill-prewarm> XML tags and apply those pre-warmed instructions immediately. Then, invoke memory_recall and memory_working_context to inject long-term and short-term working state.
3. Payload Inspection: Look up any referenced nodeId from the Mermaid canvas.
4. Execution & Offloading: If executing a tool with output >1,000 tokens, offload via memory_working_offload.
5. Citational Signals: Record memory citation outcomes via memory_mark_cited.
6. Passive or Manual Logging: Capture the final turn state via passive hooks or manual memory_capture_turn. This turn logging spikes the activation potentials of related skills, keeping active context charged.

The Non-Negotiable Habits

1. Before every response — recall memory & check working context

• Call memory_recall to get relevant L1 memories and the user L3 persona.
• If in a long-running debugging or coding session, call memory_working_context to fetch the high-level Mermaid task canvas and status.

memory_recall({
  sessionKey: "<conversation-id>", // ALWAYS USE THE CONVERSATION ID AS SESSION KEY
  query: "<summary of current user message>",
  activeSkill: "<current skill name, if any>"
})

2. During execution — offload large payloads

• Never paste large tool outputs, build logs, or code blocks (>1,000 tokens) back to the user or into your prompt.
• Proactively call memory_working_offload to save the payload to a reference file. The tool returns a short nodeId (e.g., w1682390-a2ef) to insert in your workspace context instead.

memory_working_offload({
  sessionKey: "<conversation-id>",
  payload: "<large tool output stdout/stderr>",
  title: "Build failure log",
  kind: "tool_output"
})

3. After every response — capture the turn (unless using passive hooks)

• If passive lifecycle hooks are registered in the host environment, you do not need to call this.
• If hooks are absent, call memory_capture_turn to store the conversation segment in L0.

---

Memory Tool Taxonomy

1. Long-Term Memory (RAG)

Tool	When to Call
memory_recall	Before every response — retrieves relevant context & persona.
memory_search	When the automatically recalled context is missing specific past details. Supports asOf for point-in-time audits.
memory_contradictions	Before making major architectural decisions or enforcing tech preferences.
memory_register_skill_hints	When activating a skill for the first time in a new project.

2. Short-Term Working Memory (Context Reduction)

Tool	When to Call
memory_working_context	At the start of a turn to retrieve the active task state and Mermaid task canvas.
memory_working_offload	To move a large payload out of the active prompt, returning a short nodeId placeholder.
memory_working_reset	At the end of a session to completely flush working directories.

3. Software Engineering Traces

Tool	When to Call
memory_task_state / _update	To read/write structured progress, blockers, and next actions.
memory_failed_attempts	To check what solutions have already been tried for a bug or problem area, preventing redundant work.
memory_file_history	To query all historical memories and evidence attached to a specific file or symbol.
memory_debug_trace_save	To save bug reproduction steps, root cause analysis, and fix summaries.
memory_handover	To generate a compact continuation note with evidence links.
memory_verify	To check a memory and update its confidence or status (active, superseded, archived).

When to Use

• Use at the start of every session or complex debugging task to load persona preferences, past engineering failed attempts, and high-level task status.
• NOT for stateless operations (e.g. running single lint tests or querying a git commit list once).

What NOT to Do

• Never paste outputs >1,000 tokens directly into conversation. Always offload them.
• Never skip memory_recall before a response.
• Never repeat failed approaches — check memory_failed_attempts when debugging.
• Limit memory tool calls to a maximum of 3 per turn to respect the latency budget.

Common Rationalizations

Rationalization	Reality
I don't need memory recall; I already know the context.	BrainRouter memory syncs user preferences and persona across multiple sessions. Skipping recall results in repetitive or off-track answers.
The log is long, but I'll paste it anyway.	Large logs (exceeding 1000 tokens) blow up the prompt context window, wasting tokens and diluting relevant instructions.

Red Flags

• Committing giant files or pasting massive build outputs (>1,000 tokens) directly in the conversation.
• Attempting a debug fix that has already been documented as a failure in memory_failed_attempts.
• Disregarding user preferences retrieved from the L3 persona.

Verification

After applying this skill, confirm:

• memory_recall or memory_working_context was called to pull relevant developer configurations.
• Large payloads or log blocks were offloaded via memory_working_offload.
• Injected memory and Persona configurations were actively referenced in the output.