renfei-design/design-jarvis/memory

Skill: Memory System

Manage Design Jarvis persistent memory with a Core + Archive model: keep the small,

durable project state in context and search/load deeper history only when needed.

Purpose

Memory lets Jarvis accumulate project-specific intelligence across sessions without polluting every turn with stale history. The system separates:

• Core memory — current working context that should fit in a small prompt block.
• Structured metadata — machine-readable pointers for retrieval and maintenance.
• Archive memory — decisions, sessions, raw traces, and older notes loaded on demand.

Architecture: Core + Archive

Only memory.md should be loaded automatically at project start. Use manifest.json to decide what else to read or search.

Loading discipline:

1. Read .jarvis/memory/projects/<slug>/memory.md.
2. Read manifest.json if you need file pointers, topics, or decision IDs.
3. Search or read archive files only when the task needs deeper history.
4. Never eagerly load all sessions, decisions, or raw traces.

Directory Structure

.jarvis/
└── memory/
    ├── projects/
    │   └── <project-slug>/
    │       ├── memory.md          ← CORE: compact current state
    │       ├── manifest.json      ← metadata for retrieval and maintenance
    │       ├── decisions.md       ← status-based decision log
    │       ├── artifacts.json     ← Figma/code/spec references
    │       ├── sessions/          ← concise session summaries
    │       └── archive/           ← old context, raw traces, compressed notes
    ├── preferences.md             ← user style + workflow preferences
    ├── patterns.md                ← cross-project design patterns
    └── library-cache/             ← reusable library/component references

File Responsibilities

memory.md — Core project state

Keep this current, compact, and useful at session start. It is not a changelog.

Recommended sections:

• Project overview
• Current focus
• Constraints
• Active decisions summary
• Key artifacts
• Recent outcome
• Next step
• Deep links / pointers

manifest.json — Retrieval metadata

Use valid JSON so tools can parse it. Keep it small:

{
  "schemaVersion": 1,
  "slug": "project-slug",
  "updated": "YYYY-MM-DD",
  "topics": ["topic-a", "topic-b"],
  "activeDecisionIds": ["D1"],
  "importantFiles": ["memory.md", "decisions.md"],
  "sessionCount": 0,
  "artifactFile": "artifacts.json"
}

decisions.md — Status-based decision log

Store all decisions in one file. Do not move decisions between active/archive files. Use status fields instead.

Allowed statuses: Draft, Active, Under Review, Superseded, Retired.

artifacts.json — External references

Track durable references such as Figma files, pages, nodes, specs, prototypes, and code deliverables. Prefer IDs and paths over prose.

sessions/ and archive/

Session summaries are episodic memory. Raw traces and older details belong in archive/, including archive/auto-log/YYYY-MM-DD.md for optional Figma write logs.

Memory Operations

Session start

1. Identify the active project slug.
2. Read memory.md.
3. If the request depends on prior decisions/artifacts, read manifest.json.
4. Search or read specific archive files only when pointed to by memory.md,

manifest.json, or the user's request.

During a session

• Durable project state changed → update memory.md.
• Decision made or changed → append/update an entry in decisions.md; refresh

manifest.json.activeDecisionIds.

• Artifact created or renamed → update artifacts.json and manifest.json.
• User preference learned → update root preferences.md.
• Reusable pattern learned → update root patterns.md.

Session end

1. Write a concise summary to sessions/YYYY-MM-DD.md.
2. Update memory.md with current focus, recent outcome, and next step.
3. Refresh manifest.json (updated, topics, active decisions, session count,

important files).

1. Compact old sessions into archive/ when they stop being useful individually.

Consolidation

Consolidation is a periodic, file-only maintenance pass that keeps memory lean and background-safe. It is idempotent (running twice changes nothing the second time) and non-destructive (history is moved to archive/, never deleted; decisions change status, never disappear).

Thresholds — read from manifest.json.consolidation, falling back to these defaults when the key is absent:

Steps:

1. Load memory.md and manifest.json (plus the consolidation thresholds).
2. Sessions pass — if the sessions/ count exceeds archiveAfter, keep the newest

keepSessions verbatim and append the rest to archive/sessions-YYYYMM.md (grouped by each session's own year-month), then delete the rolled-up files. Dedupe repeated outcomes during the roll-up.

1. Decisions pass — in decisions.md: flag Active entries older than staleDecisionDays

as Under Review with a dated note; when a newer decision shares a Topic, mark the older one Superseded + Superseded by: D#; compact Retired/Superseded bodies to a one-line stub (ID, title, status, link).

1. Core budget pass — if memory.md exceeds coreSoftLimit lines, move overflow detail

into the current session summary or archive/, keeping the canonical sections intact.

1. Metadata — revalidate manifest.json and artifacts.json as JSON; refresh updated,

sessionCount, activeDecisionIds, and importantFiles.

1. Report — emit a consolidation report (template in

references/memory-formats.md) summarizing what moved, what was flagged, and confirming no data was lost.

Triggers: manual ("consolidate memory"), budget-driven (at session end when sessions/ exceeds archiveAfter or memory.md exceeds coreSoftLimit), or autonomous in a background run.

Size Budgets

Behavioral Rules

1. Core stays small. memory.md is the only default load and must remain compact.
2. Status beats file moves. Decisions live in decisions.md; lifecycle is tracked

with status fields.

1. Metadata stays valid. manifest.json and artifacts.json must be valid JSON.
2. Search before loading archives. Use targeted search for old context.
3. No sensitive data. Memory may exist on disk or be committed in examples; do not

store secrets, credentials, personal data, or private customer details.

1. Graceful degradation. If memory files do not exist, initialize the core files.
2. Tell the user. Briefly mention when memory is loaded, saved, or migrated.

Full templates and examples → references/memory-formats.md