Update to Basic Memory Cloud

{
  "name": "memory-literary-analysis",
  "description": "Analyze a complete literary work into a structured Basic Memory knowledge graph. Covers schema design, entity seeding, chapter-by-chapter processing, cross-referencing, validation, and visualization.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 354
    }
  ],
  "skill_md_contents": "---\nname: memory-literary-analysis\ndescription: \"Analyze a complete literary work into a structured Basic Memory knowledge graph. Covers schema design, entity seeding, chapter-by-chapter processing, cross-referencing, validation, and visualization.\"\n---\n\n# Memory Literary Analysis\n\nTransform a complete literary work into a structured knowledge graph. Characters, themes, chapters, locations, symbols, and literary devices become interconnected notes — searchable, validatable, and visualizable.\n\n## When to Use\n\n- Analyzing a novel, play, poem, or non-fiction book end-to-end\n- Building a teaching or study resource for a literary text\n- Creating a book club companion knowledge base\n- Research projects requiring structured close reading\n- Stress-testing Basic Memory at scale (~200+ notes, 1000+ relations)\n\n## Pipeline Overview\n\n```\nPhase 0: Setup         → project, schemas, directory structure\nPhase 1: Seed          → stub notes for known major entities\nPhase 2: Process       → chapter-by-chapter notes in batches\nPhase 3: Cross-ref     → enrich arcs, add parallels, write analysis\nPhase 4: Validate      → schema checks, drift detection, consistency\nPhase 5: Visualize     → canvas files for character webs, timelines\n```\n\n## Phase 0: Setup\n\n### Create the Project\n\n```python\ncreate_memory_project(name=\"<work-name>\", path=\"~/basic-memory/<work-name>\")\n```\n\nUse a kebab-case slug of the work's title (e.g., `great-gatsby`, `hamlet`, `beloved`).\n\n### Define Schemas\n\nWrite 6 schema notes to `schema/`. Each schema defines the entity type's fields, observation categories, and relation types. Adapt fields to fit the work — the schemas below are starting points, not rigid templates.\n\n#### Character Schema\n\n```python\nwrite_note(\n  title=\"Character\",\n  directory=\"schema\",\n  note_type=\"schema\",\n  metadata={\n    \"entity\": \"Character\",\n    \"version\": 1,\n    \"schema\": {\n      \"role(enum)\": \"[protagonist, antagonist, supporting, minor], character's narrative role\",\n      \"description\": \"string, brief character description\",\n      \"first_appearance?\": \"string, chapter or scene of first appearance\",\n      \"status?(enum)\": \"[alive, dead, unknown, transformed], character status at end of work\"\n    },\n    \"settings\": {\"validation\": \"warn\"}\n  },\n  content=\"\"\"# Character\n\nSchema for character entity notes.\n\n## Observations\n- [convention] Major characters in characters/major/, minor in characters/minor/\n- [convention] Observation categories: trait, motivation, arc, quote, appearance, relationship, symbolism, fate\n- [convention] Relations: appears_in, contrasts_with, allied_with, commands, symbolizes, associated_with\"\"\"\n)\n```\n\nAdd work-specific fields as needed — e.g., `rank` for military fiction, `house` for family sagas, `species` for fantasy.\n\n#### Theme Schema\n\n```python\nwrite_note(\n  title=\"Theme\",\n  directory=\"schema\",\n  note_type=\"schema\",\n  metadata={\n    \"entity\": \"Theme\",\n    \"version\": 1,\n    \"schema\": {\n      \"description\": \"string, what this theme explores\",\n      \"prevalence(enum)\": \"[major, minor], how central to the work\",\n      \"first_introduced?\": \"string, where theme first appears\"\n    },\n    \"settings\": {\"validation\": \"warn\"}\n  },\n  content=\"\"\"# Theme\n\nSchema for thematic analysis notes.\n\n## Observations\n- [convention] Observation categories: definition, manifestation, evolution, counterpoint, quote, interpretation\n- [convention] Relations: embodied_by, contrasts_with, reinforced_by, explored_in, expressed_through\"\"\"\n)\n```\n\n#### Chapter Schema\n\n```python\nwrite_note(\n  title=\"Chapter\",\n  directory=\"schema\",\n  note_type=\"schema\",\n  metadata={\n    \"entity\": \"Chapter\",\n    \"version\": 1,\n    \"schema\": {\n      \"chapter_number\": \"integer, sequential chapter number\",\n      \"pov?\": \"string, point-of-view character or narrator mode\",\n      \"setting?\": \"string, primary location\",\n      \"narrative_mode?(enum)\": \"[dramatic, expository, reflective, epistolary, mixed], chapter's primary mode\"\n    },\n    \"settings\": {\"validation\": \"warn\"}\n  },\n  content=\"\"\"# Chapter\n\nSchema for chapter-level analysis notes.\n\n## Observations\n- [convention] Chapters stored in chapters/ directory\n- [convention] Observation categories: summary, event, tone, technique, quote, significance, foreshadowing\n- [convention] Relations: features, set_in, explores, contains, employs, follows, precedes, parallels\"\"\"\n)\n```\n\n#### Location Schema\n\n```python\nwrite_note(\n  title=\"Location\",\n  directory=\"schema\",\n  note_type=\"schema\",\n  metadata={\n    \"entity\": \"Location\",\n    \"version\": 1,\n    \"schema\": {\n      \"description\": \"string, what this place is\",\n      \"location_type(enum)\": \"[city, building, landscape, body_of_water, region, fictional, vehicle], type of place\",\n      \"real_or_fictional(enum)\": \"[real, fictional, both], whether the place exists\"\n    },\n    \"settings\": {\"validation\": \"warn\"}\n  },\n  content=\"\"\"# Location\n\nSchema for location and setting notes.\n\n## Observations\n- [convention] Observation categories: description, atmosphere, symbolism, significance, geography\n- [convention] Relations: setting_for, associated_with, symbolizes, contains, part_of\"\"\"\n)\n```\n\n#### Symbol Schema\n\n```python\nwrite_note(\n  title=\"Symbol\",\n  directory=\"schema\",\n  note_type=\"schema\",\n  metadata={\n    \"entity\": \"Symbol\",\n    \"version\": 1,\n    \"schema\": {\n      \"description\": \"string, what the symbol is literally\",\n      \"symbol_type(enum)\": \"[object, animal, color, action, natural_phenomenon, body_part], category of symbol\",\n      \"primary_meaning\": \"string, most common interpretation\"\n    },\n    \"settings\": {\"validation\": \"warn\"}\n  },\n  content=\"\"\"# Symbol\n\nSchema for symbolic element notes.\n\n## Observations\n- [convention] Observation categories: meaning, appearance, ambiguity, interpretation, quote, evolution\n- [convention] Relations: represents, associated_with, appears_in, contrasts_with, located_at\"\"\"\n)\n```\n\n#### LiteraryDevice Schema\n\n```python\nwrite_note(\n  title=\"LiteraryDevice\",\n  directory=\"schema\",\n  note_type=\"schema\",\n  metadata={\n    \"entity\": \"LiteraryDevice\",\n    \"version\": 1,\n    \"schema\": {\n      \"description\": \"string, what the device is\",\n      \"device_type(enum)\": \"[rhetorical, structural, figurative, narrative, dramatic], category\",\n      \"frequency(enum)\": \"[pervasive, frequent, occasional, rare], how often used\"\n    },\n    \"settings\": {\"validation\": \"warn\"}\n  },\n  content=\"\"\"# LiteraryDevice\n\nSchema for literary technique and device notes.\n\n## Observations\n- [convention] Observation categories: definition, usage, effect, example, significance\n- [convention] Relations: used_in, characterizes, expresses, related_to\"\"\"\n)\n```\n\n### Directory Structure\n\n```\n<project>/\n  schema/            # 6 schema definitions\n  chapters/          # one note per chapter/section + prologue/epilogue\n  characters/\n    major/           # protagonist, antagonist, key supporting\n    minor/           # named characters with limited roles\n  themes/            # thematic analysis notes\n  locations/         # settings and places\n  symbols/           # symbolic elements\n  literary-devices/  # techniques and devices\n  analysis/          # cross-cutting synthesis\n  tasks/             # processing tracker\n```\n\n## Phase 1: Seed Entities\n\nBefore processing chapters, create stub notes for major entities so `[[wiki-links]]` resolve from the start.\n\n### Characters (major)\n\nFor each major character, create a stub with known metadata:\n\n```python\nwrite_note(\n  title=\"<Character Name>\",\n  directory=\"characters/major\",\n  note_type=\"Character\",\n  tags=[\"character\", \"major\", \"<role>\"],\n  metadata={\"role\": \"<role>\", \"description\": \"<brief description>\"},\n  content=\"\"\"# <Character Name>\n\n## Observations\n- [role] <Character's role in the work>\n- [appearance] <Key physical description>\n\n## Relations\n- associated_with [[<Related Character>]]\n- appears_in [[<Key Location>]]\"\"\"\n)\n```\n\n### Seed Checklist\n\nIdentify the work's major entities before you start reading. A good starting inventory:\n\n| Type | Typical Count | What to Include |\n|------|--------------|-----------------|\n| Characters (major) | 8-20 | Protagonist, antagonist, key supporting cast |\n| Themes | 5-12 | Central concerns the work explores |\n| Locations | 4-10 | Primary settings, symbolically significant places |\n| Symbols | 4-10 | Recurring objects, images, or motifs with layered meaning |\n\nStubs don't need to be complete — they give `[[wiki-link]]` targets and will be enriched during chapter processing.\n\n## Phase 2: Chapter Processing\n\n### Source Text Preparation\n\nObtain the full text and identify chapter/section boundaries. For public domain works, Project Gutenberg is a good source. For copyrighted works, work from a physical or licensed digital copy.\n\n### Batching Strategy\n\nProcess ~10 chapters per batch to balance depth with progress. Group by narrative arc or thematic focus:\n\n| Batch | Typical Content |\n|-------|----------------|\n| 1 | Opening: setting, character introductions, world-building |\n| 2-3 | Rising action: conflicts established, relationships develop |\n| 4-6 | Middle: complications, turning points, thematic deepening |\n| 7-8 | Climax approach: escalation, revelations, crises |\n| Final | Climax, resolution, epilogue |\n\nAdjust batch size based on chapter length and density. Short, action-heavy chapters can be batched in larger groups; long, philosophically dense chapters may need smaller batches.\n\n### Per-Chapter Workflow\n\nFor each chapter:\n\n**1. Read the chapter carefully.** If working from a source text file, read the relevant section.\n\n**2. Create the chapter note:**\n\n```python\nwrite_note(\n  title=\"Chapter <N> - <Title>\",\n  directory=\"chapters\",\n  note_type=\"Chapter\",\n  tags=[\"chapter\", \"<arc-phase>\"],\n  metadata={\n    \"chapter_number\": <N>,\n    \"pov\": \"<narrator or POV character>\",\n    \"setting\": \"<primary location>\",\n    \"narrative_mode\": \"<mode>\"\n  },\n  content=\"\"\"# Chapter <N> - <Title>\n\n## Observations\n- [summary] <1-2 sentence synopsis>\n- [event] <Key plot events>\n- [tone] <Emotional and stylistic atmosphere>\n- [technique] <Notable narrative techniques>\n- [quote] \"<Significant passage>\"\n- [significance] <Why this chapter matters to the whole>\n- [foreshadowing] <Hints at future events>\n\n## Relations\n- features [[<Character>]]\n- set_in [[<Location>]]\n- explores [[<Theme>]]\n- contains [[<Symbol>]]\n- employs [[<Literary Device>]]\n- follows [[Chapter <N-1> - <Previous Title>]]\n- precedes [[Chapter <N+1> - <Next Title>]]\"\"\"\n)\n```\n\n**3. Enrich related entities:**\n\n```python\nedit_note(\n  identifier=\"characters/major/<character-slug>\",\n  operation=\"append\",\n  heading=\"Observations\",\n  content=\"\"\"- [arc] Ch.<N>: <What happens to this character>\n- [quote] \"<Attributed quote>\" (Ch.<N>)\"\"\"\n)\n```\n\n**4. Track progress** using the memory-tasks skill to create a processing task that survives context compaction.\n\n### What to Capture Per Chapter\n\n| Category | What to Look For |\n|----------|-----------------|\n| `[summary]` | 1-2 sentence chapter synopsis |\n| `[event]` | Key plot events (actions, revelations, arrivals) |\n| `[tone]` | Emotional and stylistic atmosphere |\n| `[technique]` | Narrative innovations (POV shifts, structural experiments, genre blending) |\n| `[quote]` | Memorable or thematically significant passages |\n| `[significance]` | Why this chapter matters to the whole |\n| `[foreshadowing]` | Hints at future events |\n\n### Entity Enrichment Per Chapter\n\nAs each chapter is processed, append observations to relevant entities:\n- **Characters**: `[arc]` moments, new `[trait]` revelations, `[quote]` attributions\n- **Themes**: `[manifestation]` in this chapter, `[evolution]` shifts\n- **Symbols**: `[appearance]` with context, new `[interpretation]` angles\n- **Locations**: `[atmosphere]` as described, `[significance]` in scene\n- **Literary devices**: `[example]` from this chapter\n\n### Adding Prose and Interpretation\n\nAfter the structured observations are in place, consider adding interpretive prose to major entity notes. Prepend 2-4 paragraphs of critical essay before the Observations section using `edit_note(operation=\"prepend\")`. This prose should:\n\n- Argue for a reading of the character, theme, or symbol — not just describe it\n- Connect the entity to the work's larger concerns and to literary tradition\n- Include subjective opinions clearly marked as such (\"In my reading...\", \"I find...\")\n- Ground claims in textual evidence cited by chapter number\n\nThe prose adds the interpretive texture that structured observations alone cannot capture.\n\n## Phase 3: Cross-Referencing\n\nAfter all chapters are processed:\n\n### Character Arcs\nFor each major character, write a full `[arc]` summary observation covering their trajectory across the work.\n\n### Theme Evolution\nFor each theme, add `[evolution]` observations tracing how it develops from introduction to resolution.\n\n### Chapter Parallels\nAdd `parallels` and `contrasts_with` relations between structurally similar chapters (e.g., mirrored scenes, repeated settings, thematic echoes).\n\n### Analysis Notes\nCreate synthesis notes in `analysis/`:\n\n```python\nwrite_note(\n  title=\"Narrative Structure\",\n  directory=\"analysis\",\n  note_type=\"note\",\n  tags=[\"analysis\", \"structure\"],\n  content=\"\"\"# Narrative Structure\n\nAnalysis of the work's narrative architecture.\n\n## Observations\n- [structure] <Overall arc description>\n- [technique] <Key narrative strategies>\n...\n\n## Relations\n- analyzes [[<Protagonist>]]\n- analyzes [[<Key Character>]]\n- explores [[<Central Theme>]]\n...\"\"\"\n)\n```\n\nRecommended analysis notes:\n- **Narrative Structure** — overall architecture and pacing\n- **Work Overview** — synthesis of the complete work (summary, thesis, legacy)\n- **Critical Reception** — historical and contemporary interpretations\n\n### Discover Emergent Entities\nDuring chapter processing, new minor characters, locations, and symbols will emerge. Create notes for any that appear in 3+ chapters or carry thematic weight.\n\n## Phase 4: Validation\n\n### Schema Validation\n\n```python\n# Validate each entity type\nschema_validate(noteType=\"Character\")\nschema_validate(noteType=\"Theme\")\nschema_validate(noteType=\"Chapter\")\nschema_validate(noteType=\"Location\")\nschema_validate(noteType=\"Symbol\")\nschema_validate(noteType=\"LiteraryDevice\")\n```\n\n### Drift Detection\n\n```python\nschema_diff(noteType=\"Character\")\n# ... for each type\n```\n\nFix issues found — common fixes:\n- Missing required observation categories → add them via `edit_note`\n- Enum values outside allowed set → correct metadata\n- Fields in notes but not schema → add as optional to schema if legitimate\n\n### Relation Consistency\nSpot-check bidirectional relations: if Chapter X `features [[Character]]`, does Character have observations referencing Chapter X? Fix gaps.\n\n## Phase 5: Visualization\n\nGenerate canvas files for visual exploration:\n\n```python\n# Character relationship web\ncanvas(query=\"type:Character AND role:protagonist OR role:antagonist OR role:supporting\")\n\n# Theme connections\ncanvas(query=\"type:Theme\")\n\n# Chapter timeline with key events\ncanvas(query=\"type:Chapter\", layout=\"timeline\")\n```\n\n## Adapting to Other Genres\n\nThis pipeline works for any literary text. Adjust schemas for genre:\n\n| Genre | Schema Adjustments |\n|-------|-------------------|\n| **Novel** | Base schemas work as-is; add genre-specific Character fields as needed |\n| **Play** | Add `Act` and `Scene` schemas; Character gets `speaking_lines` field |\n| **Poetry collection** | Replace Chapter with `Poem`; add `form`, `meter`, `rhyme_scheme` fields |\n| **Non-fiction** | Replace Chapter with `Section`; add `Argument`, `Evidence` schemas |\n| **Short story collection** | Add `Story` schema with `narrator`, `setting`, `word_count` |\n| **Epic/myth** | Add `Deity`, `Prophecy` schemas; Location gets `mythological_significance` |\n| **Memoir** | Character schema gets `relationship_to_narrator`; add `Memory` schema |\n\n### Scaling Guidance\n\n| Work Length | Batch Size | Estimated Notes |\n|-------------|-----------|----------------|\n| Novella (~40K words) | 5-10 chapters | ~50-80 |\n| Novel (~80K words) | 8-12 chapters | ~100-150 |\n| Long novel (~200K+ words) | 10-15 chapters | ~200-300 |\n| Series (multiple volumes) | 1 volume at a time | ~200+ per volume |\n\n## Related Skills\n\n- **memory-schema** — Schema creation, validation, and drift detection\n- **memory-tasks** — Track chapter processing progress across context compaction\n- **memory-notes** — Note writing patterns, observation categories, wiki-links\n- **memory-ingest** — Processing external input into structured entities\n- **memory-metadata-search** — Querying notes by frontmatter fields\n- **memory-lifecycle** — Archiving completed analysis phases\n\n## Guidelines\n\n- **Seed before processing.** Create entity stubs first so wiki-links resolve immediately during chapter processing.\n- **Batch for sanity.** Processing ~10 chapters at a time balances depth with momentum. Track progress with a Task note.\n- **Read the source text.** Don't rely on memory or summaries. Read (or re-read) the actual text for each batch before creating notes. Textual evidence is everything.\n- **Observations are your index.** The knowledge graph's value comes from categorized observations. Be generous with categories and specific with content.\n- **Relations are your web.** Every chapter should link to characters, themes, locations, and devices. Every entity should link back to chapters where it appears.\n- **Enrich iteratively.** Entity notes grow richer with each chapter. Don't try to write the perfect character note upfront — append as you go.\n- **Add prose for depth.** After structured data is in place, add interpretive essays to major notes. The prose captures what observations cannot: argument, nuance, opinion, and voice.\n- **Validate periodically.** Run `schema_validate` after each batch, not just at the end. Catch drift early.\n- **Quote generously.** Literary analysis lives on textual evidence. Include significant quotes as `[quote]` observations with chapter attribution.\n- **Review and revise.** After completing all chapters, review the full graph from an external perspective. Look for thin notes, missing connections, and gaps in coverage. The first pass is never the last.\n- **Analysis comes last.** Synthesis notes in `analysis/` should be written after all chapters are processed, when you have the full picture.\n"
}