AGENT SKILL

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 domain
  • semantic — known failure root causes, architectural decisions, conventions
  • procedural — 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...") and layer=semantic (root-cause knowledge: "this framework version has this class of bug").
  • Do NOT retrieve raw episodic trajectories here. If layers=["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

Rynaro
Rynaro/magicite

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.

★ 2
Rynaro
Rynaro/magicite

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.

★ 2
Rynaro
Rynaro/magicite

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.

★ 2
Rynaro
Rynaro/magicite

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.

★ 2
Rynaro
Rynaro/magicite

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.

★ 2
Rynaro
Rynaro/magicite

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.

★ 2