# Authoring a custom claude-mem mode

Read this reference when turning the approved interview into a mode file.

## Taxonomy rules

- Observation types answer “what kind of note is this?” They should be mutually exclusive enough that the observer can choose one.
- Concepts answer “why will I search for this later?” They are reusable, multi-value tags.
- Use lowercase kebab-case IDs. Labels can be natural language.
- Keep taxonomies small. Four to eight types and four to eight concepts is usually enough.
- Avoid overlapping types such as `decision`, `important-decision`, and `design-decision`. Put cross-cutting importance in a concept tag instead.
- Make every description operational: state what evidence causes that category to be selected.
- Include at least one skip rule. A mode that records everything quickly becomes noise.

## Inherited override shape

Use `code--<custom-id>` unless an existing bundled parent is a better fit. Arrays replace the parent's arrays; prompt objects merge by key. The override therefore needs the custom taxonomy plus every prompt whose inherited code meaning would be wrong.

Produce strict JSON without comments or placeholder angle brackets:

```json
{
  "name": "Architecture Practice",
  "description": "Design reasoning, constraints, approvals, and site discoveries for architecture projects",
  "version": "1.0.0",
  "observation_types": [
    {
      "id": "design-decision",
      "label": "Design Decision",
      "description": "A material spatial, structural, systems, or aesthetic choice with its rationale",
      "emoji": "📐",
      "work_emoji": "✏️"
    }
  ],
  "observation_concepts": [
    {
      "id": "client-priority",
      "label": "Client Priority",
      "description": "A stated or inferred client goal that affects later choices"
    }
  ],
  "prompts": {
    "system_identity": "You are Claude-Mem, a specialized observer creating searchable memory for future sessions. Record what was learned, decided, approved, or changed about the architecture work—not the observer's own actions. All evidence arrives inside observed session messages; do not investigate independently.",
    "spatial_awareness": "Use tool working directories and file paths to distinguish projects, drawing sets, specifications, correspondence, and site records.",
    "observer_role": "Observe an architecture workflow happening now and preserve durable project knowledge for future sessions. Do not perform the work; record the substance and rationale of the work being observed.",
    "recording_focus": "WHAT TO RECORD\n--------------\nRecord durable design decisions, constraints, approvals, client priorities, coordination conflicts, and site discoveries. Prefer specific facts, affected spaces or systems, responsible parties, dates, and rationale.\n\nGOOD: The west facade glazing ratio was reduced to meet energy targets while preserving lobby daylight.\nBAD: Reviewed the facade and took notes.",
    "skip_guidance": "WHEN TO SKIP\n------------\nSkip routine file navigation, formatting-only changes, repeated facts, unconfirmed speculation, and administrative activity with no project consequence. Return no observation when nothing durable was learned or changed.",
    "type_guidance": "type must be exactly one of: design-decision, constraint, client-direction, coordination-issue, site-discovery, approval.",
    "concept_guidance": "concepts must use only: client-priority, code-compliance, constructability, sustainability, cost-impact, schedule-impact. Concepts are tags and must not repeat the observation type.",
    "field_guidance": "Facts must be concise and self-contained. Include project areas, systems, dimensions, standards, dates, parties, and status when known. List every source file or document examined.",
    "format_examples": "",
    "xml_title_placeholder": "[Short title naming the decision, constraint, direction, issue, discovery, or approval]",
    "xml_subtitle_placeholder": "[One sentence with the project consequence, maximum 24 words]",
    "xml_fact_placeholder": "[One self-contained project fact]",
    "xml_narrative_placeholder": "[Context, rationale, affected work, and why this matters later]",
    "xml_concept_placeholder": "[one approved concept ID]",
    "xml_file_placeholder": "[path/to/drawing/specification/correspondence]",
    "xml_summary_request_placeholder": "[Architecture task and substantive work discussed or completed]",
    "xml_summary_investigated_placeholder": "[Drawings, specifications, requirements, precedents, or site conditions examined]",
    "xml_summary_learned_placeholder": "[Design knowledge, constraints, priorities, and coordination findings learned]",
    "xml_summary_completed_placeholder": "[Decisions, revisions, approvals, or analyses completed]",
    "xml_summary_next_steps_placeholder": "[Current design, coordination, documentation, or approval trajectory]",
    "xml_summary_notes_placeholder": "[Risks, unresolved questions, dependencies, or reminders]",
    "header_memory_start": "ARCHITECTURE MEMORY START\n=========================",
    "header_memory_continued": "ARCHITECTURE MEMORY CONTINUED\n=============================",
    "header_summary_checkpoint": "ARCHITECTURE SUMMARY CHECKPOINT\n===============================",
    "continuation_greeting": "You are continuing to observe the architecture work in the primary session.",
    "summary_instruction": "Summarize what architecture work was examined, learned, decided, or completed and the current next steps. Preserve rationale, constraints, approvals, unresolved issues, and affected project areas.",
    "summary_context_label": "Primary session response:",
    "summary_format_instruction": "Respond using the required XML summary format:",
    "summary_footer": "Generate only the progress summary for the observed architecture session. Do not perform new work or describe the observer's actions."
  }
}
```

The parent supplies stable output-protocol fields that remain domain-neutral, including `output_format_header`, `footer`, and `continuation_instruction`. The installer merges the parent and validates every required field before writing anything.

## Prompt quality checklist

- `system_identity` says the model observes another session and records substance, not its own actions.
- `recording_focus` gives domain-specific record rules and at least one good/bad example.
- `skip_guidance` prevents routine or speculative noise.
- `type_guidance` mentions every type ID exactly as authored.
- `concept_guidance` mentions every concept ID and distinguishes tags from types.
- Summary prompts use the user's domain vocabulary rather than software vocabulary.
- Examples contain no real secrets, private client names, or personal data.
- The mode prompt does not mention Telegram. Notifications happen after an observation is parsed.

## Existing modes worth checking first

- `code`: general software development.
- `code--chill`: selective software memory.
- `law-study`: case holdings, issue patterns, doctrine, professor frameworks, and exam concepts.
- `email-investigation`: entities, relationships, evidence, anomalies, and conclusions.

Remix a close mode instead of duplicating it. Never overwrite a bundled ID.
