Narrative Graph MCP

Narrative Graph MCP

A Model Context Protocol (MCP) server implementing the Random Tree Model (RTM) for hierarchical narrative memory in AI systems.

Overview

The Narrative Graph MCP provides a scientifically-grounded implementation of the Random Tree Model, a cognitive architecture for organizing and recalling narrative information. Based on research in statistical physics and cognitive science, it models how humans encode, compress, and recall meaningful information across different levels of abstraction.

Key Features

• Hierarchical Memory Encoding: Recursively partitions narratives into tree structures
• Working Memory Constraints: Models cognitive limits with configurable K (branching) and D (depth) parameters
• Statistical Ensembles: Generates multiple tree instances to capture population-level variance
• Compression Analysis: Calculates compression ratios and scaling properties
• Flexible Traversal: Access summaries at different abstraction levels
• Scale Invariance: Identifies universal scaling laws in long narratives

Architecture

The project follows a clean, modular TypeScript architecture:

Installation

Prerequisites

• Node.js 18+
• npm or yarn package manager

Install Dependencies

Building

Build for Production

This compiles TypeScript to JavaScript in the dist/ directory.

Development Mode

This runs TypeScript compiler in watch mode for development.

Running the Server

Start the Server

Or directly:

MCP Integration

Configure Your MCP Client

Add the Narrative Graph MCP to your MCP client configuration:

Available Tools

1. rtm_create_narrative_tree

Creates a single Random Tree encoding of a narrative.

Parameters:

• text (string, required): The narrative text to encode
• title (string, required): Title of the narrative
• type (string, optional): Type of narrative - 'story', 'article', 'dialogue', 'technical', 'other' (default: 'other')
• maxBranchingFactor (number, optional): Maximum child nodes per parent, K parameter (default: 4)
• maxRecallDepth (number, optional): Maximum traversal depth, D parameter (default: 6)

Example:

Returns: Tree ID, statistics, and encoding metadata

2. rtm_generate_ensemble

Generates a statistical ensemble of Random Trees to model population-level recall variance.

Parameters:

• text (string, required): The narrative text to analyze
• title (string, required): Title of the narrative
• ensembleSize (number, optional): Number of trees to generate (default: 100)
• maxBranchingFactor (number, optional): K parameter (default: 4)
• maxRecallDepth (number, optional): D parameter (default: 6)

Example:

Returns: Ensemble statistics, variance analysis, and scale invariance properties

3. rtm_traverse_narrative

Traverses a narrative tree at specified depths to retrieve summaries at different abstraction levels.

Parameters:

• text (string, required): The narrative text to traverse
• title (string, required): Title of the narrative
• traversalDepth (number, required): Depth to traverse, 1-10 (controls abstraction level)
• maxBranchingFactor (number, optional): K parameter (default: 4)
• maxRecallDepth (number, optional): D parameter (default: 6)

Example:

Returns: Summaries at the specified depth, compression ratios, and recall sequence

4. rtm_find_optimal_depth

Finds the optimal traversal depth to achieve a target recall length.

Parameters:

• text (string, required): The narrative text to analyze
• title (string, required): Title of the narrative
• targetRecallLength (number, required): Target number of clauses to recall
• maxBranchingFactor (number, optional): K parameter (default: 4)
• maxRecallDepth (number, optional): D parameter (default: 6)

Example:

Returns: Optimal depth and accuracy metrics

Usage Examples

Basic Narrative Encoding

Generate Population Model

Get Different Summary Levels

Troubleshooting

Server Startup Issues

If the server disconnects immediately after starting:

1. Check that all dependencies are installed: npm install
2. Ensure the build is complete: npm run build
3. Check for TypeScript errors: npm run type-check
4. Run with debug output: DEBUG=* node dist/index.js

Common Errors

• "Tool not found": Ensure the tool name is spelled correctly
• "Invalid parameters": Check that required parameters are provided
• "Build errors": Run npm run clean && npm run build

Development

Code Style

The project uses ESLint and Prettier for code formatting:

Type Checking

Testing

Theory and Background

The Random Tree Model is based on research showing that human memory for narratives follows specific mathematical patterns:

1. Hierarchical Organization: Stories are mentally organized into nested levels of abstraction
2. Working Memory Constraints: Limited capacity (K~4) constrains how much can be held in mind
3. Compression: Longer narratives are increasingly summarized, following predictable ratios
4. Scale Invariance: Very long narratives exhibit universal scaling properties

For more details, see the foundational paper: "Random Tree Model of Meaningful Memory" by Zhong et al.

Contributing

Contributions are welcome! Please ensure:

1. All code is TypeScript with proper type annotations
2. Functions include JSDoc comments
3. New features include corresponding tests
4. Code passes linting and type checks

License

MIT

Acknowledgments

This implementation is based on the Random Tree Model theoretical framework from cognitive science and statistical physics research.