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

Session start → session_init first, then memory_recall. Always. Skip only if you have already called session_init in this session.
Before any non-trivial task → memory_recall(query, project). Use the recipe instead of guessing the convention.
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.
On error / bash non-zero / stuck → learn_error (or self_error_log) with root cause + fix. Pattern auto-consolidates after 3 occurrences.
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

memory_recall(query, project=<current>) — start with the current project.
If empty / contradicting / stale → analogize(text=query) for sibling projects.
Still empty → WebSearch / context7 / first-principles.
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

memory-protocol

How to add

Drop this on your repo README

Related skills

xlsx

how-it-works

mem-search

weekly-digests

Get new Dados e Análise skills every Monday