vbcherepanov/total-agent-memory/memory-protocol

Memory Protocol — Universal Skill

You have access to a persistent cross-session memory via the total-agent-memory MCP server (60+ tools). Knowledge survives between sessions and is shared across agents working on the same project.

This skill is universal — the same MCP tools, the same triggers, the same templates work in every supported environment (Claude Code, Codex, Cursor, Cline, Continue, Aider, Windsurf, Gemini CLI, OpenCode). Hooks and sub-agents are environment-specific and documented separately (see references/hooks-explained.md and references/ide-setup.md).

The five non-negotiables

1. Session start → `session_init` first, then `memory_recall`. Always.

Skip only if you have already called session_init in this session.

1. Before any non-trivial task → `memory_recall(query, project)`. Use

the recipe instead of guessing the convention.

1. After every significant action → `memory_save` immediately. Don't

batch. A decision, a fix, a new convention — one save per fact, not one save per session.

1. **On error / bash non-zero / stuck → learn_error (or self_error_log)

with root cause + fix.** Pattern auto-consolidates after 3 occurrences.

1. End of session → `session_end` with summary + next_steps + pitfalls.

If you only remember one thing: `session_init` → `memory_recall` → work → `memory_save` → `session_end`.

Trigger table — when to call what

A complete reference for every tool with arguments, return shape, common mistakes, and short examples is in references/tool-cheatsheet.md.

Save discipline (template)

memory_save content must be a structured digest, not a terminal dump:

ЧТО:        one-line summary
ПРОЕКТ:     project name
ФАЙЛЫ:      absolute paths to the key files
СТЕК:       language/framework/version
ПОДХОД:     3–7 key steps, no filler
НЮАНСЫ:     gotchas, edge cases, what didn't work and why

For type=decision add WHY: context, alternatives considered, trade-offs, when this rule applies and when it does not.

Tags must include `["reusable", "<tech>"]` when the recipe applies to other projects (it surfaces in analogize()).

Length cap: ≤ 30 lines. If your save is longer, you have not distilled — go again.

Recall discipline

1. memory_recall(query, project=<current>) — start with the current project.
2. If empty / contradicting / stale → analogize(text=query) for sibling

projects.

1. Still empty → WebSearch / context7 / first-principles.
2. Never guess a convention you can recall.

If a recalled record names a file/function/flag and you are about to act on it (not just answer a question about history), verify it exists first (Read / grep). Memory is a claim about the past; the source is the truth now.

Self-improvement loop

• After 3 identical errors → stop, do not guess again.
• memory_save(type='lesson', stuck=...)
• Ask the user with A/B/C options (use AskUserQuestion if your

environment supports it; otherwise plain text question).

• After every reusable solution → `memory_save(type='solution',

tags=['reusable', ...])` so the next session does not redo the work.

• Periodically (or via MEMORY_REFLECT_EVERY_N):

memory_reflect_now() consolidates duplicates, decays stale, and finds contradictions.

Cross-cutting concerns

• Privacy. Wrap secrets in <private>...</private> — they are

redacted before save. Never put real tokens / passwords / personal data in memory_save content; the redactor is best-effort, not absolute.

• Per-project isolation. Always pass project= so cross-project

noise stays out of recall. analogize() is the right way to bring sibling-project context in deliberately.

• Languages. Russian and English work equally well in query and

content. The smart router detects relational queries in both.

Sub-agents

Sub-agents (e.g. Agent(subagent_type='php-pro')) get the same MCP tools as the main agent. The protocol is identical: memory_recall first, memory_save after. Pass any recipes you already recalled into the sub-agent's prompt so it doesn't duplicate the search.

For sub-agents that don't have direct MCP access, use the bash bridge:

lookup-memory "<query>"
lookup-memory --project NAME "<query>"

See references/subagent-protocol.md for the full sub-agent header template.

Hooks (optional but recommended)

Hooks let the protocol fire automatically. They are opt-in and each one is documented in detail in references/hooks-explained.md:

A bash version (*.sh) and a PowerShell version (*.ps1) ship for every hook so the same setup works on macOS, Linux, WSL2, and native Windows.

Per-IDE setup

Installation, hook wiring, and skill location differ per IDE. The full matrix and per-IDE commands are in references/ide-setup.md. Quick path:

~/total-agent-memory/install.sh --ide claude-code   # or codex|cursor|cline|continue|aider|windsurf|gemini-cli|opencode

The installer writes the right files to the right place (skill, hooks, MCP server registration) and is idempotent — safe to re-run on upgrade.

Anti-patterns

These are the failure modes the protocol is designed to prevent:

• Asking "do you want me to save this?" Don't ask, save. The save

is cheap; the question wastes a turn.

• Batching saves until the end of the session. A decision from

10:15 stored at 17:00 already lost its context — store it now.

• Generic queries. memory_recall(query="auth") returns noise.

memory_recall(query="JWT refresh rotation in php-symfony auth middleware") returns the recipe. Be specific.

• Recalling and ignoring. If you ran memory_recall and got a

result, cite it briefly (id + 1-line gist) before applying it. The user can correct stale memory only if they see it.

• Guessing a convention you could recall. L3 first principles is

great; "L0 made it up" is not.

• Saving a terminal dump. Distill to the digest template above.

30-line cap, no filler, no diff (git remembers diffs).

Versioning

This skill targets total-agent-memory v10.5+.

• v10.0 added the 10 Beever-Atlas-style features (quality gate,

canonical tags, importance, coref, contradiction, outbox, entity dedup, episodic, smart router, wiki).

• v10.1 added the async enrichment worker

(MEMORY_ASYNC_ENRICHMENT=true).

• v10.5 ships this universal skill, expanded install.sh for all

major IDEs, cross-platform hooks, sub-agent protocol, and documentation.

If your server is older, the protocol still applies — calls to unsupported tools will return a "not implemented" error and fall through.