/memory-protocol

name: memory-protocol
version: 10.5.0
description: >
  Universal protocol for total-agent-memory MCP server.
  Activate at session start, before any non-trivial task, after every significant
  action, on errors, and at session end.
  Relevant whenever the user mentions: memory, recall, past context, decisions
  history, conventions, lessons learned, "продолжаем", "сохранись", "resume",
  or any reference to prior sessions / cross-session knowledge.
  Works with Claude Code, Codex CLI, Cursor, Cline, Continue, Aider,
  Windsurf, Gemini CLI, OpenCode, and any client that speaks MCP.
keywords:
  - memory_recall
  - memory_save
  - session_init
  - session_end
  - kg_add_fact
  - workflow_predict
  - self_rules_context

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. 2. **Before any non-trivial task → `memory_recall(query, project)`.** Use the recipe instead of guessing the convention. 3. **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. 4. **On error / bash non-zero / stuck → `learn_error` (or `self_error_log`) with root cause + fix.** Pattern auto-consolidates after 3 occurrences. 5. **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. 3. Still empty → `WebSearch` / `context7` / first-principles. 4. **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), ver