Memory for AI agents. Protocol for context, state, and handoffs across sessions.

AI agents are stateless. Every session starts from zero. They:

• Can't load everything (limited context window)
• Lose state between sessions
• Hallucinate structure they haven't seen
• Can't hand off to the next agent

A protocol that makes sessions compound instead of restart:

1. VIEWs tell agents what to load for their current task
2. SYNC files track state so agents remember
3. Handoffs let agents communicate across sessions

# Install
pip install ngram

# Initialize in your project
ngram init

# Check protocol health
ngram validate

# Check project health (monoliths, stale docs, etc.)
ngram doctor

# Auto-fix issues with agents
ngram work

# Get documentation context for a file
ngram context src/your_file.py

# Generate bootstrap prompt for LLM
ngram prompt

# Expose local port 3005 via ngrok
ngrok http 3005 --url trusted-magpie-social.ngrok-free.app

# Run FalkorDB MCP server
cd ~/FalkorDB-MCPServer
npm run dev

# Restart full stack (FalkorDB, BE, FE, MCP server, ngrok)
tools/run_stack.sh

After initialization:

your-project/
├── AGENTS.md                    # Updated with protocol bootstrap
└── .ngram/
    ├── PROTOCOL.md              # Core rules (agents read this)
    ├── PRINCIPLES.md            # Working principles
    ├── CLAUDE.md                # Updated with protocol bootstrap
    ├── views/                   # Task-specific context instructions
    ├── templates/               # Templates for documentation
    └── state/
        └── SYNC_Project_State.md  # Current project state

ngram doctor              # Full report
ngram doctor --level critical  # Only critical issues
ngram doctor --format json     # JSON output

Checks for:

• Monolith files (>500 lines code, >1000 lines docs)
• Undocumented code directories
• Stale SYNC files (>14 days old)
• Placeholder docs (unfilled templates)
• Incomplete doc chains

ngram work              # Fix all issues
ngram work --max 3      # Limit to 3 agents
ngram work --dry-run    # Preview what would be fixed

Spawns agents (Claude or Codex) to autonomously fix issues found by doctor.

Points agents to the protocol:

# ngram

Before any task, read: .ngram/PROTOCOL.md
For task-specific context: .ngram/views/

Each VIEW tells agents what to load for a specific task type:

# VIEW: Implement

## LOAD FIRST
1. .ngram/state/SYNC_Project_State.md
2. docs/{area}/{module}/PATTERNS_*.md
3. docs/{area}/{module}/SYNC_*.md

## AFTER CHANGES
Update: docs/{area}/{module}/SYNC_*.md

Available views: Implement, Debug, Test, Review, Refactor, Document, Onboard, and more.

Living documents tracking current state:

• What's working
• What's in progress
• Handoffs for next session

This is how agents "remember" across sessions.

For each module:

docs/{area}/{module}/
├── PATTERNS_*.md    # WHY this design
├── BEHAVIORS_*.md   # WHAT it should do
├── ALGORITHM_*.md   # HOW it works
├── VALIDATION_*.md  # HOW to verify
└── SYNC_*.md        # WHERE we are now

Agents navigate: Code ↔ Docs bidirectionally.

1. Agents don't load everything — They load ONE view for their task
2. State is explicit — SYNC files track what's happening
3. Sessions compound — Work accumulates instead of restarting
4. Protocol over intelligence — Structure enables capability

MIT

Developed by Mind Protocol. Issues and PRs welcome.