| 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
- 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 in
references/ide-setup.md. Quick path:
~/claude-memory-server/install.sh --ide claude-code
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.
