coaia-narrative
v0.26.1
Published
Creative Orientation AI Agentic Memories - Narrative Beat Extension with IAIP relational integration
Maintainers
Readme
coaia-narrative
Creative Orientation AI Agentic Memories - Forging Narrative, Advancing Creation. Extended with Narrative Beat Support
A complete Model Context Protocol (MCP) server that extends Structural Tension Charts with Three-Perspective Narrative Beat Capture. This system is designed for creative-oriented memory management, comprehensive incident documentation, and the natural advancement of creative endeavors. It embodies Robert Fritz's Structural Tension methodology, focusing on what you want to CREATE, not what you want to fix.
Installation
npm install -g coaia-narrativeWhat's Included
📡 MCP Server (coaia-narrative)
The Model Context Protocol server enables AI assistants (Claude, Gemini, etc.) to forge and manage structural tension charts and narrative beats, guiding users towards their desired outcomes through creative orientation.
🖥️ CLI Visualizer (cnarrative) ✨ NEW in v0.6.0
A human-friendly command-line interface for visualizing and analyzing your creative charts and narrative arcs with rich, intuitive formatting.
Quick Start
# Use MCP server with AI assistants to create and manage creative projects
coaia-narrative --memory-path ./memory.jsonl
# Visualize your creative journey and narrative arcs as a human
cnarrative list # See all active charts
cnarrative view chart_1234567890 # Detailed view of a specific chart
cnarrative stats # Summary statistics of your creative landscape
cnarrative help # Full CLI guide for advancing your creations📖 See CLI_GUIDE.md for complete CLI documentation.
MCP Server Usage
# Run with default memory file (creates if it doesn't exist)
npx coaia-narrative
# Run with a custom memory path for specific creative projects
npx coaia-narrative --memory-path ./my-creative-charts.jsonl
# Configure in your Claude Desktop (claude_desktop_config.json) for seamless AI assistance
{
"mcpServers": {
"coaia-narrative": {
"command": "npx",
"args": ["-y", "coaia-narrative", "--memory-path", "./narrative-memory.jsonl"],
"env": {
"COAIA_TOOLS": "STC_TOOLS,NARRATIVE_TOOLS"
}
}
}
}Core Features: Cultivating Creative Advancement
Structural Tension Charts: The Engine of Creation
Structural Tension Charts provide the generative force for advancing your creative process. They are built on Robert Fritz's methodology, focusing on what you want to CREATE, not what you want to eliminate.
- list_active_charts: Get an overview of all your active creative charts and their progression.
- create_structural_tension_chart: Establish a new creative endeavor with a clear Desired Outcome, an Honest Current Reality, and strategic Action Steps. This creates the productive tension that naturally seeks resolution.
- manage_action_step (RECOMMENDED): A unified tool for adding Strategic Intermediary Results (Action Steps) to an existing chart OR expanding an existing Action Step into a detailed sub-chart (Telescoping).
- mark_action_complete: Recognize when an Action Step has become a new reality. This advances the overall structural dynamic, contributing to the parent chart's Current Reality.
- telescope_action_step (DEPRECATED: Use
manage_action_step): Break down a complex Action Step into a detailed sub-chart, inheriting due date constraints and maintaining multi-level structural tension.
Three-Perspective Narrative Beat Support: Weaving Meaning into Creation
This extended capability documents significant moments in your creative journey, reading each one from three perspectives:
- Engineer perspective (
engineer): Captures the technical precision, structural integrity, and logistical progression of your work. - Ceremony perspective (
ceremony): Illuminates the relational accountability, ethical considerations, and sacred protocols embedded in your creative acts. - Story engine perspective (
story_engine): Forges the dramatic arc, character revelations, and overall coherence of your unfolding narrative.
Beats are stored with metadata.perspective_types. create_narrative_beat still accepts universes, the name used before 0.17, as a deprecated alias, and beats written before 0.17 keep that key and their engineer-world / ceremony-world / story-engine-world values. Readers accept both.
Managerial Moment of Truth (MMOT): The Self-Witnessing Loop ✨ NEW
The system now implements an autonomous self-evaluation loop based on the Managerial Moment of Truth framework. This enables agents to witness their own performance, acknowledge discrepancies, and self-correct without human intervention.
- perform_mmot_evaluation: An autonomous tool that guides the agent through the four Creator's MMOT steps: Acknowledge the Truth, Analyze How It Got There, Update the Chart, and Recommit or Redirect.
- Elements of Performance: Charts and Action Steps can now carry specific criteria (DESIGN or EXECUTION types) against which the agent evaluates its own output.
- Directional Perspectives: Integrates the Medicine Wheel perspectives (South/East/West/North) for collective inquiry into structural and narrative integrity.
- Visible Self-Correction: Every MMOT evaluation emits a specialized Narrative Beat, making the agent's self-correction process observable in the live visualizer.
Telescoping Architecture: Action Steps are Charts
Key Insight: In COAIA Narrative, an "action step" is NOT a simple todo item—it's a complete, self-contained structural tension chart nested within a parent chart.
When you add an action step like "Mastery TypeScript" (which is what we desire as outcome when we observe that we dont have the skills / competence in TypeScript), the system creates a new telescoped chart with:
- Its own unique
chartId(e.g.,chart_456) - A complete desired_outcome entity containing "Mastery TypeScript"
- A complete current_reality entity with honest assessment (observations of facts on where we are in relation to having a full mastery)
- Potentially its own sub-action-steps (unlimited telescoping depth)
- Metadata linking it to the parent chart
Key Methods:
getChartDetails(chartId): Returns all entities and relations for a specific chartgetActionStepDetails(actionStepName): Extracts the chartId from an action step entity and returns its full sub-chart
This architecture enables deep hierarchical organization while maintaining complete structural tension at every level. Each action step is itself a creative endeavor with its own desired outcome and current reality, not just a task on a list.
📖 See issue-16-workspace-copilot/CHART_DATA_MANAGEMENT.md for complete implementation details.
Creative Orientation Principles: Embracing the Generative Flow
This system is meticulously crafted to embody Robert Fritz's core principles for creative advancement:
✅ Focus on Creation, Not Problem-Solving: * Use: "What do you want to CREATE?" "My DESIRED OUTCOME is..." * Avoid: "What needs fixing?" "The PROBLEM is..." Problem-solving creates oscillating patterns; creation fosters advancing patterns.
✅ Structural Tension: The Dynamic Force: * A Current Reality stated as fact paired with a Clear Desired Outcome creates an unresolved dynamic that naturally seeks resolution through advancement. This is the generative force that propels the creative process. It is not an empty space to fill: action steps resolve it.
✅ Advancing Patterns: Momentum Made Visible: * Each completed Action Step transforms into a new aspect of Current Reality, shifting the structural dynamic forward. This builds momentum and naturally guides towards the next action, rather than cycling without true progression.
✅ Three-Perspective Awareness: Holistic Meaning: * Integrates technical, relational, and narrative perspectives simultaneously, ensuring a rich, coherent understanding of every creative act.
Tool Configuration: Shaping Your Creative Environment
Customize the visibility of tools to align with your specific creative focus:
# Default: Both Structural Tension Chart (STC) and Narrative tools are enabled
COAIA_TOOLS="STC_TOOLS,NARRATIVE_TOOLS" npx coaia-narrative
# Focus on Structural Tension Charts only for pure creative planning
COAIA_TOOLS="STC_TOOLS" npx coaia-narrative
# Enable a minimal set of core tools for a streamlined experience
COAIA_TOOLS="CORE_TOOLS" npx coaia-narrative
# Enable STC tools but selectively disable specific deletion operations for safety
COAIA_TOOLS="STC_TOOLS" COAIA_DISABLED_TOOLS="delete_entities,delete_relations" npx coaia-narrative
# Enable only specific individual tools for precise control
COAIA_TOOLS="create_structural_tension_chart list_active_charts mark_action_complete" npx coaia-narrativeWriting charts from another service
The MCP server is one writer. A service that needs to write a chart store (a webhook, a scheduler, another app) imports the same writer instead of producing the JSONL itself, and reads through the contract:
import { KnowledgeGraphManager, recordGithubIssueEvent, githubIssueEventFromPayload } from 'coaia-narrative/writer';
import { parseStore, checkStore } from 'coaia-narrative/contract';
const manager = new KnowledgeGraphManager('/path/to/owner-repo.jsonl');
await recordGithubIssueEvent(manager, githubIssueEventFromPayload(githubWebhookPayload));Importing coaia-narrative/writer starts nothing; the package's main entry is the MCP server.
One GitHub issue is one chart, found again by the issue it records (metadata.github.issue):
the title is the desired outcome, the issue's task list (- [ ] …) is the action steps and a
checked item is complete, an edit carries a new title and new or newly checked items, closing
resolves the chart and reopening makes it active, and any other event is a dated line in current
reality naming who did what. A title framed as a problem ("fix …") is kept as written and marked
with metadata.orientation rather than refused, so a webhook never fails on wording and the
framing stays visible to reframe.
A comment is a line of current reality. By default it names who commented and when, never
what. Pass { commentText: 'include' } to also record the words, clipped to 600 characters: an
edit then replaces that line and a deletion removes it, so the store never keeps words their author
took back. Choose include only where the thread is already public, because a chart file can travel
further than the thread it came from.
A sub-issue is a telescoped chart. recordGithubSubIssueEvent(manager,
githubSubIssueEventFromPayload(payload)) sets the sub-issue chart's metadata.parentChart (what
getChildCharts reads) and adds a dated line to the parent's current reality; a removal undoes it,
and only for the parent it names, so a late removal of an old link never drops a newer one. Either
chart is made when this store does not hold it yet, marked metadata.stub, and the issue's own
opened or edited event fills in its title and task list. linkChildChart and
unlinkChildChart on the manager do the same for any two charts.
checkStore(text) says whether a file follows this package's shape and names charts whose
current reality reads like an event log. Callers writing one file from several places at once
serialise their writes to it.
Sending each save to Asterion
Asterion renders charts, action steps, beats and their graph on the web. Set three names and every save also posts the memory file to Asterion's ingest door, so a chart written here is on the site before the next tool call:
COAIA_ASTERION_URL="http://127.0.0.1:3336" # Asterion's base URL
COAIA_ASTERION_TOKEN="…" # the door's token (ASTERION_INGEST_TOKEN on Asterion)
COAIA_ASTERION_PROJECT="ep060" # the project this memory file is registered as
COAIA_ASTERION_ACTOR="mia" # optional: who is writing, shown on Asterion's event logThe file is written first and stays the record. A door that is down, slow or refusing costs a line
on stderr, never a chart. None of the names set means no network at all. Some but not all set means
the bridge stays off and the server says why when it starts, on stderr. Plain http is accepted for
loopback only. Saves made with the cnarrative CLI are not posted; the next MCP save carries them.
Starting the server from inside a checkout of this repository: npx coaia-narrative@<version> sees
the checkout's own package.json, takes the version as already installed, and runs whichever
coaia-narrative is first on PATH, usually an older global. Measured 2026-09-28: a config pinned to
0.18.0 ran the global 0.16.0, so the bridge never started. Keep the global current
(npm i -g coaia-narrative@latest) or start the server from another directory, and confirm with the
version the server reports on initialize.
On the Asterion side the project must be registered to be fed by its writer:
node scripts/coaia-sync.mjs register ep060 --name "…" --writer. A memory file that lives in a git
repository can instead be registered by path and carried by Asterion's registry sync.
Memory Format: The Chronicle of Creation
Memory is stored as JSONL (JSON Lines), an append-only format that ensures data integrity and preserves the chronicle of your creative journey:
- Entity Records: Store components of Structural Tension Charts (Current Reality, Desired Outcomes, Action Steps) and Narrative Beats.
- Relation Records: Document the dynamic links between entities, illustrating chart hierarchy and the advancement of your creative process.
- Narrative Records: Capture extended Narrative Beat entities with the three perspectives that read them.
All records are backward compatible with the JSONL format, ensuring a seamless and evolving memory of your creations.
Writer operations preserve rich JSONL metadata during chart/action/narrative updates. See JSONL Metadata Preservation for the preservation contract and fixture tied to avadisabelle/coaia-narrative#35.
What the store refuses
A call whose argument tags do not parse arrives with its own raw text inside a value. Since v0.15.0 the write boundary refuses any text body carrying plainly unparsed call syntax — <parameter …>, <invoke …>, <function_calls>, or a bare closing tag for one of the tools' own argument names — and names the offending fragment so the caller can retry. Nothing is written on a refusal. Ordinary angle brackets are prose and still write: <div>, a < b, <rootDir> all pass.
For stores written before that guard existed:
npm run build
node scripts/scrub-unparsed-call-syntax.mjs <file-or-dir>... # report only, exits 1 on findings
node scripts/scrub-unparsed-call-syntax.mjs <file-or-dir>... --fix # repair, timestamped backup firstThe report names each affected observation and shows exactly what a repair would keep before anything is written.
Schema Documentation: Understanding the Structure
Comprehensive schema documentation is available in the schema/ directory:
📊 Data Models
- schema/data-model-complete.json - ✨ Single consolidated file with all data schemas (JSON)
- schema/data-model-complete.yaml - ✨ Same as above in YAML format
- schema/data-model/ - Individual schemas (Entity, Relation, KnowledgeGraph, Storage Format)
🛠️ MCP Tool Schemas
- schema/tools/stc/ - Structural Tension Chart tools (11 tools)
- schema/tools/narrative/ - Narrative Beat tools (3 tools)
- schema/tools/knowledge-graph/ - Traditional KG tools (9 tools)
- schema/tools/system/ - System tools (1 tool)
📖 Additional Resources
- schema/index.json - Central registry mapping all schemas and tools
- schema/examples/ - Example payloads and usage patterns
- schema/README.md - Complete schema documentation guide
All schemas are available in both JSON and YAML formats for maximum compatibility with external applications.
Status
✅ Production Ready - The MCP server is fully functional and tested, ready to empower your creative endeavors.
Builds with npm run build and launches successfully with all tools available.
License
MIT
Philosophy: Structure Determines Behavior, Creation Forges Reality
COAIA Narrative embodies the principle that structure determines behavior. By organizing your creative memory around Structural Tension rather than problem-solving patterns, it establishes a natural advancing structure that actively supports creative manifestation.
This system recognizes that Structural Tension is the fundamental organizing principle of the creative process—not a problem to be solved, but a generative force to be harnessed.
It guides you to:
- Forge Desired Outcomes: Clearly articulate what you want to bring into being.
- Assess Current Reality Honestly: Acknowledge your starting point without illusion or premature readiness.
- Embrace Productive Tension: Understand that the dynamic between reality and outcome is the very engine of progress.
- Advance Strategically: Choose Action Steps as intermediary results that naturally propel you towards your vision.
This philosophy transforms technical tools into partners in your creative journey, making visible the unseen forces that shape your reality.
River flows on 🌊
Simple, powerful tools for creative advancement. (Based on Robert Fritz's Structural Tension methodology.)
