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

| Event | Tool | Why | |---|---|---| | Session opens | session_init(project) | Returns previous summary + next_steps + pitfalls and marks them consumed. Call first. | | Any task starts | memory_recall(query, project) | Recipe-first; never invent a convention twice. | | Before edit/write to a file | file_context(path) | Returns risk_score + warnings (past errors on this path, hot spots). | | Before architecture choice | memory_recall + analogize(query, exclude_project) | Cross-project analogy. | | Bash returns non-zero (and reproducible) | learn_error(file, error, root_cause, fix, pattern) | Auto-consolidates to a rule after N≥3. | | Architectural decision made | save_decision(title, options, criteria_matrix, selected, rationale) | Structured; auto-tagged structured; goes into recall with decisions_only=True filter. | | Tech-stack/dependency/config change | kg_add_fact(subject, predicate, object) | Temporal; auto-invalidates old facts. | | Solution that other projects could reuse | memory_save(type='solution', tags=['reusable', '<tech>']) | Surfaces in analogize() for sibling projects. | | Reusable pattern / idiom | memory_save(type='convention') | | | Lesson learned (regression / postmortem) | memory_save(type='lesson') | Higher recall weight on similar tasks. | | Episode (story of how something was done) | memory_episode_save(narrative, outcome) | Narrative form — "what was tried, what failed, what worked". | | Error worth a one-time note | self_error_log(description, category, fix?) | Cheaper than learn_error; no auto-rule. | | User prompt that should be remembered | save_intent(prompt, project) | Auto-captured by hook if installed. | | Major task starting | workflow_predict(task_description) | If confidence < 0.3 ask the user about approach. | | Major task ending | workflow_track(workflow_id, outcome) | Trains the predictor. | | "What was the stack at date X?" | kg_at(timestamp) | Time-travel query. | | "Find similar in other projects" | analogize(text, exclude_project) | Jaccard + Dempster-Shafer fusion. | | Indexing an external repo | ingest_codebase(path, languages) | AST tree-sitter, 9 languages. | | Show recent saves chronologically | memory_timeline(limit) | Replays session → session. | | Build per-project digest | memory_wiki_generate(project) | Markdown to <MEMORY_DIR>/wikis/<project>.md. | | Session closes ("сохранись" / "save") | session_end(session_id, summary, next_steps, pitfalls) + dual-write to Obsidian if available | Picked up by next session_init. |

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:

~/claude-memory-server/ollama/lookup_memory.sh "<query>"
~/claude-memory-server/ollama/lookup_memory.sh --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:

| Hook | Trigger | Default action | |---|---|---| | session-start.sh | Session opens | Calls session_init and prints summary. | | pre-edit.sh | Before file write | Calls file_context(path) and warns if risk_score > 0.5. | | post-tool-use.sh | After every tool call | Optional: captures observation via memory_observe. | | user-prompt-submit.sh | User prompt sent | Calls save_intent. | | on-stop.sh | Session interrupted (context limit, Ctrl-C) | Writes recovery file; next session_start picks it up. |

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