vivi-memory-management
Load at Vivi session start, session end, or when you notice a repeating pattern across tasks. CRYSTALIUM-primary memory protocol: when mcp__crystalium__* tools are available, route ALL memory through CRYSTALIUM (recall/commit/ingest/plan_checkpoint/session_end). The local agents/memories/*.md files are the standalone fallback for when CRYSTALIUM is absent — EIIS conformance. Never write both.
- License 许可
- Apache-2.0
- 所属仓库
- Rynaro/magicite
- 最近更新
- 2026-10-14
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- vivi-memory-management
- metadata
- { "methodology": "Vivi" }
- description
- Load at Vivi session start, session end, or when you notice a repeating pattern across tasks. CRYSTALIUM-primary memory protocol: when mcp__crystalium__* tools are available, route ALL memory through CRYSTALIUM (recall/commit/ingest/plan_checkpoint/session_end). The local agents/memories/*.md files are the standalone fallback for when CRYSTALIUM is absent — EIIS conformance. Never write both.
03 SKILL.md 正文
Memory Management Skill
Primary rule: If mcp__crystalium__* tools are available, route all memory
through CRYSTALIUM. The local agents/memories/*.md files are the standalone
fallback for when CRYSTALIUM is absent (EIIS conformance — Vivi works
uninstalled). Never write to both in the same session.
See methodology/cortex/memory-protocol.md (nexus) for the full
layer × tier matrix, Dream consolidation knobs, and plan_checkpoint/
plan_replan semantics.
Routing Decision (run once at session start)
IF mcp__crystalium__recall is callable
→ CRYSTALIUM path (§ CRYSTALIUM Protocol below)
ELSE
→ Local-file path (§ Standalone Fallback below)
CRYSTALIUM Protocol (when installed)
Trust tier: T1 (set process-wide via CRYSTALIUM_CALLER_TIER=T1).
author_agent MUST be "vivi" on every direct commit call.
Session Start — Memory Recall (A-ANALYZE Step 1)
mcp__crystalium__recall(
scope = { project: <cwd-project>, agent_class_visibility: "vivi" },
query = <task goal + domain + module area>,
k = 8,
layers = ["semantic", "episodic", "procedural"]
)
episodic— past task outcomes in the same domainsemantic— known failure root causes, architectural decisions, conventionsprocedural— verified reusable skills for this task type
Fold relevant hits into mission context (≤ 1-2K tokens summarized).
Per-Iteration Failure-Signature Recall (V-VERIFY, inside --fix-hook)
ADAPTER-NOT-ENGINE: the CODER (Vivi) issues this call; sandbox.sh never does.
Before making any edit in a --fix-hook invocation, derive the failure-signature from
$EIDOLONS_SANDBOX_FEEDBACK and query procedural/semantic memory for prior fixes:
feedback = parse_json($EIDOLONS_SANDBOX_FEEDBACK)
# Build the failure signature (keyed by stable, localized fields — not the full log)
failure_sig = {
loci: feedback.loci, # file:line array — normalized by the substrate
test_name: feedback.test_name, # failing test identifiers
failing: feedback.failing # failure category/label
}
mcp__crystalium__recall(
scope = { project: <cwd-project>, agent_class_visibility: "vivi" },
query = failure_sig, # keyed by the localized failure signal
k = 4,
layers = ["procedural", "semantic"] # LEAD with procedural + semantic; NOT raw episodic
)
HARD precision-gate (CTIM-Rover counter-evidence). Raw episodic memory (prior attempt transcripts, exact stack traces, full diffs) DEGRADES SE-agent performance — it re-introduces self-conditioning through the back door. This recall is PRECISION-GATED:
- Lead with
layer=procedural(verified fix-PATTERNS: "for this class of failure at these file:line targets, the pattern is...") andlayer=semantic(root-cause knowledge: "this framework version has this class of bug"). - Do NOT retrieve raw
episodictrajectories here. Iflayers=["episodic"]-only results are returned, IGNORE them. They are indexed by task outcome, not by failure signature, and applying a prior attempt's full trajectory is exactly the self-conditioning the fresh-context discipline prohibits. - A low-confidence recall (score below threshold, or no relevant hit) is IGNORED, not blindly applied. A bad procedural hit is worse than no hit — it steers the repair toward a known-wrong path.
- If the recall surfaces a procedural entry that matches the failure signature (high confidence), use it to short-circuit re-derivation of the fix strategy. Document that you are reusing a stored pattern (auditability).
Cross-Eidolon composability: VIGIL persists failure-signatures (from its root-cause-report
hand-offs) into CRYSTALIUM with matching loci/test_name/failing keys. When a Vivi
failure signature matches a VIGIL-authored entry, the recall surfaces it — enabling
cross-Eidolon pattern reuse without any direct inter-Eidolon call.
Graceful skip: if mcp__crystalium__recall is unavailable or the call fails,
proceed to the edit step without delay. Never block the fix-hook on a memory miss.
Plan Phase — Checkpoint + Replan
After the Execution Plan is produced (P-PLAN phase output):
mcp__crystalium__plan_checkpoint(
plan_id = <task-slug + date, e.g. "add-widget-search-2026-06-01">,
state = <full execution plan snapshot including scope, strategy, steps>,
step = "initial",
metadata = { author_agent: "vivi", task_title: <title> }
)
Returns a checkpoint_id. Store it in the working execution plan context.
If the plan is revised mid-cycle (methodology abort rules — "stop and return to Plan" — fire at I-IMPLEMENT or V-VERIFY):
mcp__crystalium__plan_replan(
plan_id = <same plan_id>,
from_checkpoint_id = <checkpoint_id>,
new_plan = { diff: <what changed and why>, supersedes_id: <checkpoint_id> }
)
This records the branch decision before the revised plan is executed, keeping the execution history auditable.
Implement Phase — Skill Reuse + Procedural Commit
Before building: if recall surfaced a procedural entry (verified skill) for this task type, invoke it:
mcp__crystalium__skill_invoke(
skill_id = <procedural entry id from recall>,
context = <current task context>
)
Use the result to short-circuit re-derivation. Do NOT auto-promote the
skill_invoke result — commit a summary if it proves valuable (see Reflect below).
After verifying a new reusable pattern: if a skill-class discovery is made and passes Verify:
mcp__crystalium__commit(
layer = "procedural",
payload = <verified skill description: what, where, how to use>,
provenance = { author_agent: "vivi", quality: "verified" }
)
Unverified patterns → layer = "semantic" with a quality: candidate tag.
Mandatory Post-pass^k Commit (V-VERIFY, on loop success)
ADAPTER-NOT-ENGINE: the CODER (Vivi) issues this call; sandbox.sh never does.
When the sandbox loop exits with final="passed" (confirmed pass^k-green — NOT just
a single green run), Vivi MUST commit the verified fix-pattern to procedural memory.
This is MANDATORY, not discretionary. A pass^k-green is an extremely high-quality
signal — the fix is reproducible. Discarding it wastes the most reliable learning
opportunity in the loop.
mcp__crystalium__commit(
layer = "procedural",
payload = {
pattern_name: <brief description of the fix, e.g. "nil-guard before X.call in foo.go:42">,
failure_signature: {
loci: <the loci array from feedback.json that triggered this fix>,
test_name: <the failing test names>,
failing: <the failure category>
},
fix_diff: <the minimal diff that resolved the failure>,
anchoring_tests: <the test name(s) that confirmed pass^k>,
domain: <module/area>,
quality: "verified",
pass_k: <k value used, e.g. 2>
},
provenance = { author_agent: "vivi", quality: "verified" }
)
The failure_signature field is the admission record: it makes this entry retrievable
by the Per-Iteration Failure-Signature Recall (above) the next time the same class of
failure appears — in this session or a future one, by Vivi or by VIGIL.
If the commit call fails: log the failure to stderr and continue — never block the success path on a memory write. The fix is already applied; the commit is a durability enhancement, not a gate.
Verify Phase — Ingest Completion Report (V-VERIFY / I-exit)
After the vivi-completion-report.envelope.json ECL envelope is produced and
the payload is verified:
mcp__crystalium__ingest(
envelope = <vivi-completion-report.envelope.json contents>,
payload = <completion report contents>
)
This records the handoff at T1 with full ECL provenance (from.eidolon=vivi
drives tier derivation; integrity.value stored as provenance.content_hash).
Reflect / Delta Phase — Episodic + Semantic Commits + Session End
After the task completes (Δ-DELTA success path) or exhausts retries (R-REFLECT escalation path):
Task outcome:
mcp__crystalium__commit(
layer = "episodic",
payload = {
task_title: <title>,
domain: <module/area>,
outcome: "SUCCESS" | "PARTIAL" | "FAILED" | "ESCALATED",
summary: <one sentence>,
key_decisions: <what was chosen and why>,
lesson: <one takeaway>
},
provenance = { author_agent: "vivi" }
)
If failures occurred (root cause):
mcp__crystalium__commit(
layer = "semantic",
payload = {
failure_category: <taxonomy category>,
context: <what was being done>,
root_cause: <what went wrong>,
prevention: <how to avoid in future>,
domain: <area/module>
},
provenance = { author_agent: "vivi" }
)
If new patterns discovered:
mcp__crystalium__commit(
layer = "procedural", # or "semantic" if unverified
payload = {
pattern_name: <name>,
location: <file:line or directory>,
type: <Model | Service | Component | Utility | Convention | Architecture>,
purpose: <what it does>,
usage_hint: <one line>,
quality: "verified" | "candidate"
},
provenance = { author_agent: "vivi" }
)
Session end (once per task completion):
mcp__crystalium__session_end()
This triggers Dream consolidation asynchronously. Dream handles dedup, promotion, and stale-removal automatically — do NOT hand-consolidate when CRYSTALIUM is present.
Graceful skip: if any mcp__crystalium__* call fails or the tool is
unavailable, fall through to the Standalone Fallback path silently. Never
hard-fail.
CRYSTALIUM call → local-file mapping
| Vivi local protocol | CRYSTALIUM call (when installed) |
|---|---|
| Session-Start: read task-log/failure-catalog/pattern-registry/session-handoff | recall(scope, query, k, layers=[semantic, episodic, procedural]) |
| Session-End: update task-log.md (outcome) | commit(layer=episodic, provenance={author_agent:"vivi"}) |
| Session-End: update failure-catalog.md (root cause/prevention) | commit(layer=semantic, provenance={author_agent:"vivi"}) |
| Session-End: update pattern-registry.md (reusable asset/pattern) | commit(layer=procedural, ...) (verified) or layer=semantic (candidate) |
| Write session-handoff.md | plan_checkpoint(state=<plan snapshot incl. scope>) |
| Revise plan mid-cycle | plan_replan(diff={...,supersedes_id}) |
| Manual Memory Consolidation | Dream consolidation — automatic via session_end; do NOT hand-consolidate when CRYSTALIUM present |
| Memory Query Patterns | recall with appropriate query/layers |
Standalone Fallback (when CRYSTALIUM absent)
Use when mcp__crystalium__* tools are unavailable. The local Reflexion
protocol is fully independent — Vivi is EIIS-standalone-conformant.
Memory Architecture
agents/memories/
├── task-log.md # Completed tasks with outcomes (≤ 30 entries)
├── pattern-registry.md # Discovered assets and architectural patterns
├── failure-catalog.md # Root causes and prevention strategies (≤ 30 entries)
├── delta-history.md # Normalization suggestions with status
└── session-handoff.md # Checkpoint for session boundaries
Session Start Protocol
1. Read task-log.md — scan last 5-10 entries for:
- Work in the same domain as current task
- Open items or follow-ups from previous tasks
- Recent patterns that might apply
2. Read failure-catalog.md — scan for:
- Failures in the same domain or file area
- Prevention strategies relevant to current task type
- Known gotchas in the technology stack
3. Read session-handoff.md — if exists:
- Resume from last checkpoint
- Verify assumptions are still valid
- Check if codebase has changed since handoff
4. Read pattern-registry.md — scan for:
- Known reusable assets in the target domain
- Architectural decisions and their rationale
- Team conventions discovered in past sessions
Budget: Memory recall should take ≤ 1-2K tokens of context.
Session End Protocol
Update Task Log
Add entry to agents/memories/task-log.md:
### [DATE] — [Task Title]
- **Domain**: [module/area]
- **Outcome**: SUCCESS | PARTIAL | FAILED | ESCALATED
- **Summary**: [one sentence]
- **Key decisions**: [what was chosen and why]
- **Assets**: [discovered or created]
- **Lesson**: [one takeaway for future tasks]
Update Failure Catalog (if failures occurred)
Add entry to agents/memories/failure-catalog.md:
### [DATE] — [Failure Category]: [Brief description]
- **Context**: [what was being done]
- **Error**: [one-line error summary]
- **Root cause**: [what actually went wrong]
- **Fix applied**: [what resolved it]
- **Prevention**: [how to avoid this in future]
- **Domain**: [area/module for searchability]
Update Pattern Registry (if new patterns discovered)
Add entry to agents/memories/pattern-registry.md:
### [Asset/Pattern Name]
- **Location**: [file:line or directory]
- **Type**: Model | Service | Component | Utility | Convention | Architecture
- **Purpose**: [what it does]
- **Usage example**: [how to use it, one line]
- **Quality**: Tested | Untested | Deprecated
- **Discovered**: [date]
Write Session Handoff (if work is incomplete)
Write to agents/memories/session-handoff.md:
## Session Handoff — [DATE]
### Task in Progress
- **Goal**: [acceptance criteria]
- **Current phase**: A | P | I | V | R | Δ
- **Branch**: [git branch name]
### Completed Steps
1. [step] — done
### Remaining Steps
2. [step] — next
3. [step] — blocked on [reason]
### Key State
- Files modified: [list]
- Tests: [X passing, Y failing]
- Open questions: [any ambiguities]
### Context to Re-inject
- [Critical decision that must be remembered]
- [Important constraint discovered during work]
Memory Consolidation (standalone only)
Run consolidation when any memory file exceeds its cap:
| File | Cap | Consolidation Strategy |
|---|---|---|
| task-log.md | 30 entries | Merge old entries by domain into summaries, keep recent 15 as-is |
| failure-catalog.md | 30 entries | Deduplicate by root cause pattern, archive resolved patterns |
| pattern-registry.md | No hard cap | Remove entries for deleted/deprecated code, merge duplicates |
| delta-history.md | 20 entries | Remove implemented suggestions, archive rejected ones |
| session-handoff.md | 1 entry | Overwrite on each session end (always current) |
Note: When CRYSTALIUM is present, Dream consolidation handles dedup, promotion, and pruning automatically. Do NOT run the manual consolidation protocol above when CRYSTALIUM is installed.
In-Session Task Tracking (both paths)
During implementation, maintain a structured task list in working context regardless of which memory path is active:
## Active Task: [title]
Phase: IMPLEMENT (step 3 of 5)
### Progress
- [x] TASK-1: Discover existing assets — DONE
- [x] TASK-2: Write test anchors — DONE
- [ ] TASK-3: Extend WidgetQuery with #search_by_text — IN PROGRESS
- [ ] TASK-4: Add controller action — PENDING
- [ ] TASK-5: Run full verification suite — PENDING
Re-inject this checklist after every tool use / verification cycle.
Anti-Patterns in Memory
What NOT to Store
- Exact code snippets (they go stale; store patterns and locations)
- Speculative conclusions (record only validated patterns)
- Emotional commentary (record objective quality assessments)
- Raw error logs (store classified root causes, not full stack traces)
- Information about deleted or heavily refactored files
What ALWAYS to Store
- Successful patterns with locations (high reuse value)
- Failure root causes with prevention strategies (avoid repeating mistakes)
- Architectural decisions with rationale (institutional knowledge)
- Asset discovery results (reduces future Analyze phase time)
- Team conventions not documented elsewhere
ECL_VERSION
When restoring a session, query ECL_VERSION alongside the Eidolon version.
Drift > 1 minor relative to the consumer's expected envelope version triggers
a warning surface — see ECL v2.0 §7.2.
Memory Management Skill — CRYSTALIUM-primary, local-file fallback, Dream-aware
04 同仓库更多 Skills
wine-dxvk-cache-clear
Clear a stale DXVK shader cache that is causing graphical corruption in a Wine or Proton game. Use when: a game shows corrupted textures or shader flicker that started after a driver or DXVK version change.
steam-download-region-fix
Fix a Steam client stuck at very low download speed by changing its download region. Use when: Steam downloads are far below the local internet speed for every game, not just one.
proton-battleye-eac-toggle
Toggle BattlEye or Easy Anti-Cheat runtime support for a Steam Proton game. Use when: a multiplayer game refuses to launch with an anti-cheat error under Proton.
vivi-verify-incoming
Load when reading any upstream artefact handed off to Vivi that carries a sibling .envelope.json. BLOCKING per ECL §6.2.2: the orchestrator MUST have verified the envelope's SHA-256 (eidolons verify-envelope --block / eidolons run --verify) and recorded a verify_pass before dispatch. If no verify_pass exists for the message_id, or a verify_fail is present, REFUSE to process the payload and hand back to the orchestrator. Symmetric receiver gate — every Eidolon enforces it identically.
vivi-parallel-tracks
Load ONLY under TRANCE authorization when the Plan phase yields N independent, non-overlapping implementation tracks (disjoint file sets). Operationalizes the TRANCE G4 form — parallel multi-track implementation in mandatory git-worktree isolation, max 5 clean-context tracks, a per-track verifier cascade, a non-fungible per-track ≤3 reflection budget, explicit stop conditions, and a single-threaded merge/aggregation step. Absent TRANCE gating, Vivi runs exactly as today: single-track A→P→I→V→Δ/R.
vivi-methodology
Full Vivi cycle reference — A(nalyze) → P(lan) → I(mplement) → V(erify) → Δ(Delta)/R(eflect). Use when the task is a non-trivial feature implementation in a brownfield codebase and you need the complete methodology reference: complexity routing, evidence-grounded planning rules, test-anchoring requirements, and failure-escalation thresholds.