Memory System

ClaudusBridge ships a persistent shared knowledge base under Saved/ClaudusBridge/memory/. Every AI agent that drives the editor (Claude Code, Codex CLI, Cursor, Windsurf, Claude Desktop, …) can append learnings there and read what previous sessions accumulated. This is how the plugin gets more useful with every session instead of re-teaching the same lessons.

The memory system was added because of a simple observation: agents working with ClaudusBridge constantly re-discover the same gotchas (fly_to_actor wants actor, focus_viewport_on_actor wants label; UE5 graph editors all use scroll=zoom + RMB-hold=pan; material edits don't auto-apply to preview without clicking Apply; ProgressBar Percent: 0 is invisible). Without a shared store that knowledge dies at session end and the next agent walks in blind.

---

Storage layout

Saved/ClaudusBridge/memory/
  _log.jsonl     ← append-only raw entry log (one JSON per line)
  _index.md      ← auto-curated table of contents (regenerated on every write)
  framing.md     ← per-topic markdown file, most-recent first
  spawning.md
  transforms.md
  navigation.md
  materials.md
  blueprints.md
  umg.md
  niagara.md
  gotchas.md
  shortcuts.md
  process.md
  ue5_controls.md
  ...

• Topic files are markdown, append-only, most-recent entry first. Easy for both humans and agents to read.
• _log.jsonl is the raw append-only log — every entry as a single JSON line with full metadata (timestamp, from_session, kind, tags, summary, body). Use this for full-history queries.
• _index.md is auto-curated and regenerated on every memory_remember and memory_consolidate. It's a quick table of contents with topic, entry count, byte size, and last-modified.

The store is shared across all agents on the same machine. When you record a learning it benefits Codex CLI users, Cursor users, your future sessions, and any teammate using the same project.

---

MCP tools

Tool	Purpose
memory_remember	Append a learning to <topic>.md and _log.jsonl
memory_recall	Return the markdown content of a topic file (or _index.md)
memory_topics	List every topic with entry count, byte size, last-modified
memory_search	Full-text substring search across all topic files
memory_consolidate	Regenerate _index.md from current topic files

memory_remember

{
  "topic": "framing",
  "summary": "fly_to_actor uses 'actor' param, not 'label'",
  "kind": "gotcha",
  "from_session": "claude-code",
  "tags": ["fly_to_actor", "navigation", "framing"],
  "body": "focus_viewport_on_actor takes label. fly_to_actor takes actor. Calling fly_to_actor with label returns Missing actor parameter error. Working call: fly_to_actor with actor=MyCube. Sister tool focus_viewport_on_actor uses label=MyCube."
}

The topic name is normalized (lowercase, whitespace → underscores) so "Camera Framing" and "camera_framing" land in the same file. New topic files are auto-created on first remember; subsequent remembers append a markdown block at the top of the file (most-recent first).

memory_recall

// Read a specific topic
{ "topic": "framing" }

// Or omit to read the auto-curated _index.md
{}

Returns { path, topic, content, chars }. The content is the full markdown text — pipe it directly to your terminal or read it with your client's text-rendering.

memory_topics

No parameters. Returns:

{
  "topics": [
    { "topic": "framing", "entries": 4, "size_bytes": 1820, "last_modified": "2026-04-27T03:01:11.000Z", "path": "..." },
    ...
  ],
  "count": 12,
  "memory_dir": "C:/Users/.../Saved/ClaudusBridge/memory"
}

memory_search

{ "query": "fly_to_actor" }

Returns hits with a small ~200-character snippet around the first match in each topic file. Case-insensitive substring match.

---

cb shortcuts

The cb helper exposes all of these as single-line subcommands:

cb topics
cb recall                                         # the index
cb recall framing                                 # a topic
cb search fly_to_actor                            # text search

cb remember framing "fly_to_actor wants 'actor' param" \
            --kind gotcha --tags fly_to_actor,navigation \
            --body "focus_viewport_on_actor takes label..."

cb learn                                          # alias for cb recall

See The cb Helper CLI for the full subcommand reference.

---

When to record

Be liberal. The cost is one cb remember line; the value compounds every session forward. Concrete triggers:

• A parameter shape that the schema doesn't make obvious worked / didn't work
• A camera pose that frames a specific scene composition well
• A z-coordinate range that buries actors under existing terrain in this project's level
• A tool that takes a different param name than its sibling (sibling tool gotcha)
• A useful keyboard shortcut for the editor or a graph editor
• A console variable / show flag combo that helps with a specific debug task
• Any divergence between API success and visual outcome (the highest-value entries — these are exactly what EYES MANDATORY exists to catch)

Don't record:

• Things the schema already documents clearly
• One-off project-specific values that won't generalize (e.g. "the BP_Player in this project has 3 children")
• Anything you're not sure about — accuracy beats volume

---

Suggested topic taxonomy

Topic naming is free-form (auto-normalized). To keep the store coherent across agents and projects, prefer these established topics:

Topic	What goes here
framing	Camera poses, viewport setups, view modes that work for specific scenes
spawning	Actor placement patterns, common z-ranges, label conventions
transforms	Location / rotation / scale tricks, array vs scalar forms
navigation	Moving through scenes, fly_to_actor, focus, orbit
materials	Material graph patterns, parameter binding, recompile gotchas
blueprints	Node arrangements, common subgraphs, BP creation recipes
umg	Widget layouts, anchor presets, animation patterns
niagara	Emitter / module tricks, common VFX recipes
gotchas	Tools that no-op silently, parameter footguns
shortcuts	cb shortcuts, UE5 keybinds, console commands
ue5_controls	Engine-level controls (graph editor scroll = zoom, RMB = pan, etc.)
process	Workflow patterns (iterative dialogue, eyes-mandatory, dual watcher)
editor_state	Read-only snapshots, get_editor_state usage
viewport	Realtime mode, view modes, show flags

New topics auto-create on first remember — don't worry about pre-creating.

---

Reading at session start

As one of your first actions on any non-trivial editor task, read the index:

cb topics                          # see what's been learned
cb recall                          # full index with table of contents
cb recall <topic>                  # drill into a specific topic
cb search <keyword>                # find a learning by substring

This is cheap (single MCP call) and prevents you from re-discovering known gotchas. Do it before you spawn any sub-agents — they'll often hit the same patterns the index already documents.

---

Recording at session end (or as you go)

Whenever you discover anything worth saving — record it immediately. Don't batch at the end; you'll forget the details. Records are cheap and additive; bad records can be edited (the topic files are plain markdown).

Format conventions:

• Summary is one line, headline-style. "fly_to_actor uses 'actor', not 'label'" — readable as a list item.
• Body has the details: exact tool calls that worked, what failed first, the fix. Include enough that the next agent can act on it without re-discovering.
• Tags are free-form CSV (--tags a,b,c in cb remember). Useful for cb search later.
• Kind is tip (positive learning), gotcha (footgun avoided), pattern (reusable recipe), shortcut (handy abbreviation), note (default), or fundamental (rare; for foundational rules like EYES MANDATORY).

---

Worked example: the iterative-dialogue session

In one session a user spawned three specialist sub-agents (UMG / Materials / Blueprints) without mandatory captures. All three compiled clean but rendered visually broken. After fixing them with a re-spawned Visual-Fixer sub-agent, the lessons recorded:

process / kind=fundamental
  "STREAMING IS THE AGENT EYES — without it the agent is blind"
  Body explains the API-success-vs-visual-success gap with three real
  examples (M_HoloPanel black, BP events disabled, WBP bars stacked).

gotchas / kind=gotcha
  "Material edits don't auto-apply to preview — Apply button required"
  Body: even after recompile_material returns success, click Apply
  in toolbar (around 240,64) to push shader to preview.

umg / kind=gotcha
  "Slot positioning uses LayoutData, not Position"
  Body: set_slot_property rejects "Position" but accepts the full
  LayoutData struct with Anchors + Offsets.

umg / kind=gotcha
  "ProgressBar Percent: 0 is invisible despite color set correctly"
  Body: set Percent=0.5+ to vision-verify color.

shortcuts / kind=shortcut
  "Graph editor navigation: scroll=zoom, RMB-hold=pan, F=focus"
  Body: applies to all UE5 graph editors (Blueprint, Material,
  Niagara, AnimGraph, MetaSound, BehaviorTree).

These five entries alone save the next agent a substantial fraction of a session's worth of dead ends. Multiply across many sessions and many topics, and the plugin's effective skill ceiling rises continuously.

---

Maintenance

Topic files are plain markdown. You can edit them by hand if needed (re-order entries, fix typos, consolidate duplicates) — just call memory_consolidate afterward to refresh _index.md.

_log.jsonl is the canonical raw log; don't edit it (you'll break parseability). It's there for full-history queries that the markdown files can't easily serve (filter by from_session, kind, tags, time range).

Memory is per-project (under <project>/Saved/ClaudusBridge/memory/). Knowledge from one Unreal project doesn't automatically leak into another. If you want shared learnings across projects, copy individual topic files manually.

---

Next steps

• EYES MANDATORY — the rule that produces most of the highest-value memory entries
• Iterative Dialogue — the workflow that surfaces learnings worth recording
• The cb Helper CLI — the fastest path to remember / recall / search
• Multi-Agent Coordination — how multiple sub-agents share memory cleanly