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:

narrative-graph-mcp/
├── src/
│   ├── core/              # Core RTM implementation
│   │   ├── rtm-math.ts    # Mathematical utilities
│   │   ├── rtm-builder.ts # Tree construction
│   │   ├── rtm-traversal.ts # Tree navigation
│   │   └── rtm-ensemble.ts # Statistical ensembles
│   ├── types/             # TypeScript type definitions
│   │   └── rtm.ts         # RTM data structures
│   ├── tools/             # MCP tool implementations
│   │   ├── createNarrativeTree.ts
│   │   ├── generateEnsemble.ts
│   │   ├── traverseNarrative.ts
│   │   └── findOptimalDepth.ts
│   └── index.ts           # MCP server entry point
├── dist/                  # Compiled JavaScript
├── tsconfig.json          # TypeScript configuration
└── package.json           # Project dependencies

Installation

Prerequisites

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

Install Dependencies

npm install

Building

Build for Production

npm run build

This compiles TypeScript to JavaScript in the dist/ directory.

Development Mode

npm run dev

This runs TypeScript compiler in watch mode for development.

Running the Server

Start the Server

npm start

Or directly:

node dist/index.js

MCP Integration

Configure Your MCP Client

Add the Narrative Graph MCP to your MCP client configuration:

{
  "mcpServers": {
    "narrative-graph-mcp": {
      "command": "node",
      "args": ["/path/to/narrative-graph-mcp/dist/index.js"],
      "env": {}
    }
  }
}

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:

{
  "text": "Once upon a time, in a distant kingdom...",
  "title": "The Lost Kingdom",
  "type": "story"
}

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:

{
  "text": "Once upon a time, in a distant kingdom...",
  "title": "The Lost Kingdom",
  "ensembleSize": 200
}

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:

{
  "text": "Long narrative text...",
  "title": "Research Paper",
  "traversalDepth": 3
}

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:

{
  "text": "Long narrative text...",
  "title": "Research Paper",
  "targetRecallLength": 50
}

Returns: Optimal depth and accuracy metrics

Usage Examples

Basic Narrative Encoding

// Encode a story into a hierarchical tree
const result = await tools.call('rtm_create_narrative_tree', {
  text: "Once upon a time, in a distant kingdom, there lived a wise king...",
  title: "The Lost Kingdom",
  type: "story"
});

Generate Population Model

// Generate ensemble to model how different people might recall the story
const ensemble = await tools.call('rtm_generate_ensemble', {
  text: "Once upon a time, in a distant kingdom...",
  title: "The Lost Kingdom",
  ensembleSize: 200
});

Get Different Summary Levels

// Get high-level summary (depth 1)
const abstract = await tools.call('rtm_traverse_narrative', {
  text: "Long narrative text...",
  title: "Research Paper",
  traversalDepth: 1
});

// Get detailed summary (depth 4)
const detailed = await tools.call('rtm_traverse_narrative', {
  text: "Long narrative text...",
  title: "Research Paper",
  traversalDepth: 4
});

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:

npm run lint
npm run format

Type Checking

npm run type-check

Testing

npm test
npm run test:watch
npm run test:coverage

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.