🧠 Ultraflow

Persistent brain memory + token tracking for AI coding agents
Works seamlessly with Claude Code, OpenCode, Codex, and OpenClaw

🎯 What It Does

Ultraflow is your AI agent's nervous system—a persistent memory layer that survives sessions, tracks every token spent, automatically delegates to OpenCode for FREE, and intelligently loads context when needed.

Core Capabilities

| 🧠 Brain | 💭 DreamLord | 🎁 OpenCode | ✨ Lyra | 🤖 Ruflo | |:---|:---|:---|:---|:---| | 18 MCP tools | Context management | FREE delegation | Prompt optimization | Multi-agent coord | | Semantic search | Checkpoint system | Smart routing | Platform-specific modes | Cost tracking | | Persistent storage | Token tracking | Cost optimization | Clarity analysis | Parallel execution | | Memory clustering | Budget alerts | Auto task routing | Optimization tips | Agent logging |

Integrated Tools

| 📊 Graphify | 💾 MemPalace | 🔗 GitNexus | |:---|:---|:---| | Knowledge graphs | Local AI memory | Code intelligence | | 25+ languages | 29 MCP tools | Execution flows | | Relationship mapping | Semantic search | Impact analysis | | Auto-analysis | Auto-indexing | Refactoring safety |

In 30 Seconds

# Install globally
npm install -g @s-nikk/ultraflow

# Or install locally
npm install @s-nikk/ultraflow

# Initialize (auto-detects your agent)
ultraflow init

# Start everything
ultraflow start

# Ultraflow dashboard appears at http://localhost:3000
# TokenTracker (multi-tool token dashboard) at http://localhost:7680

That's it! Memory, multi-tool token tracking, OpenCode delegation, and 18 MCP tools are now available.

Next Step: Ask your coding agent to set up and wire Ultraflow. It will auto-detect the running server and integrate all 18 MCP tools into your workflow. No manual configuration needed—your agent will handle it.

🚀 What More It Can Do

Advanced Features (Already Built)

Brain automatically:

• Summarizes long conversation histories
• Keeps important details, discards noise
• Learns bidirectionally from prior sessions
• Classifies memories: user profiles, feedback patterns, project context, external references

// Save a memory once, search across all sessions
await brain.save_memory({
  name: 'auth-pattern',
  content: 'JWT tokens stored in httpOnly cookies, refresh on 401',
  type: 'reference'
});

// Later: intelligent search across sessions
const matches = await brain.search_memories('authentication best practices');

Ultraflow automatically routes non-critical work to OpenCode (FREE), reserving Claude tokens for complex reasoning only:

What goes to OpenCode (FREE):

• Code generation & boilerplate
• Test writing & test data
• Documentation generation
• Simple refactoring
• Analysis & planning
• Error fixing & debugging

What stays on Claude (paid):

• Architectural decisions
• Complex problem-solving
• Security/performance reviews
• Novel design patterns
• Code review & approval

Example Flow:

// Ultraflow sees: "Generate API tests"
// Routes to: OpenCode:Nemotron (FREE)
// Returns: Full test suite, $0 cost

// Ultraflow sees: "Design auth architecture"
// Routes to: Claude Haiku (pays $0.01+)
// Returns: Vetted design with tradeoffs

Cost Impact:

• Without Ultraflow: $12.50 (125K tokens @ $0.10/1K)
• With Ultraflow: $3.75 (70% reduction)
  • OpenCode: $0 (50K tokens, boilerplate/analysis)
  • Haiku: $1.25 (12.5K tokens, decisions only)
  • Compressed context: $2.50 (savings on all interactions)

DreamLord monitors and optimizes token spending:

• Real-time cost tracking per model
• Budget alerts when approaching limits
• Cost predictions before running tasks
• Auto-suggests cheaper alternatives
• Dashboard shows per-model costs and savings opportunities

Dashboard insights:

├─ Total tokens: 45,230
├─ Total cost: $1.24
├─ Budget remaining: $3.76 (43% of $5.00)
├─ Cost per interaction: $0.031
│
└─ Optimization opportunities:
   • Use Haiku instead of Sonnet: +$0.42 savings
   • Compress context by 15%: +$0.18 savings
   • Delegate to OpenCode: +$0.95 savings

Safe /clear without losing progress:

// Before clearing context
await dreamlord.generateCheckpoint({
  summary: 'Completed auth system with OAuth2',
  nextSteps: 'Implement rate limiting',
  tags: ['auth', 'phase-1', 'complete']
});

// Later: resume exactly where you left off
const checkpoint = await dreamlord.loadCheckpoint({ id: '...' });

Automatic context degradation detection—refresh memories when context gets stale.

Ruflo coordinates multiple AI agents in parallel:

npx ultraflow ruflo dispatch \
  --agent "claude-code" \
  --agent "opencode:nemotron" \
  --task "Analyze database schema" \
  --task "Generate migrations"

Cost tracking per agent, parallel execution, unified memory.

• Find memories by concept, not just keywords
• Automatic memory clustering
• Similarity-based retrieval
• Memory relevancy over time (decay older memories)

Lyra analyzes and optimizes prompts for clarity, context, scope:

npx ultraflow lyra "Generate a React form with validation" -m detail

# Output: Optimized prompt with specific input/output format
# Techniques used, improvements found, pro tips

Works with platform-specific modes: Claude, ChatGPT, Gemini, OpenCode, Codex.

📋 Usage Examples (Summarized, Cool)

Example 1: Save & Search Memories Across Sessions

# Session 1: Learn something
claude> "Hey, save that database pattern we just worked out"
brain.save_memory({
  name: 'postgres-indexing',
  content: '...',
  type: 'reference'
})
# ✅ Saved

# Session 2 (next day): Instant recall
claude> "What was that database pattern?"
brain.search_memories('postgres') 
# ✅ Returns: postgres-indexing + 3 related memories

Example 2: Token Tracking in Real-Time (Multi-Tool)

# TokenTracker Dashboard: http://localhost:7680
# Tracks across 11 AI coding tools (Claude Code, Cursor, Gemini, Codex, OpenCode, Codex, Kiro, etc.)
# Shows:
# ├─ Total tokens: 45,230 (across all tools)
# ├─ Total cost: $1.24
# ├─ Tool breakdown: Claude Code, OpenCode, Gemini, etc.
# ├─ Budget used: 25%
# ├─ Cost per interaction: $0.031
# └─ Top optimization: "Use Haiku for code review (+$0.42 savings)"

Example 3: Safe Context Clear with Checkpoint

// Before /clear:
await brain.generateCheckpoint({
  summary: 'Built authentication with JWT',
  nextSteps: 'Rate limiting, CORS config',
  tags: ['auth', 'complete']
});

// Later (fresh session):
const context = await brain.loadContext();
// Returns checkpoint + relevant memories auto-loaded

Example 4: OpenCode Delegation (FREE Tokens)

# Request: "Generate comprehensive API tests"
# Ultraflow detects: Non-critical work
# Routes to: OpenCode:Nemotron (FREE)
# Result: Full test suite, $0 cost

# Compare:
# ❌ Without delegation: $0.08 (Haiku cost)
# ✅ With delegation: $0.00 (OpenCode FREE)
# Savings: $0.08 per request

Example 5: Multi-Agent Cost Tracking

# Dispatch to multiple agents
npx ultraflow ruflo dispatch \
  --agent "claude-haiku" \
  --agent "opencode:nemotron" \
  --task "Design auth system" \
  --task "Generate tests"

# Dashboard shows:
# ├─ Haiku: 2,048 tokens, $0.02 (critical decisions)
# ├─ OpenCode: 5,900 tokens, $0.00 (tests + analysis)
# └─ Total cost: $0.02 (vs $0.12 if both Haiku)
# ✅ 83% cost savings

🎯 Feature Comparison

| Feature | Ultraflow | DIY Memory | No System | |---------|:---------:|:----------:|:---------:| | Persistent Memory | ✅ | ❌ | ❌ | | Semantic Search | ✅ | ⚠️ (manual) | ❌ | | Token Tracking | ✅ | ❌ | ❌ | | Cost Optimization | ✅ | ❌ | ❌ | | Multi-Agent Coord | ✅ | ❌ | ❌ | | Auto-Detection | ✅ | ❌ | ❌ | | Zero Config | ✅ | ❌ | ❌ |

🛠️ Installation & Setup

Quick Install

npm install ultraflow

Initialize for Your Agent

npx ultraflow init

Auto-detects: Claude Code • OpenCode • Codex • OpenClaw

Start Services

# Both dashboard + MCP server
npx ultraflow start

# Just dashboard
npx ultraflow start dashboard

# Just MCP server
npx ultraflow start brain

Check Status

npx ultraflow status

📚 MCP Tools (58+ Total)

🧠 Brain Memory Tools (5)

• search_memories — Find by keyword or concept
• get_memory — Retrieve full content
• list_memories — Index all saved memories
• refresh_index — Update from disk
• save_memory — Persist new memories

🔄 Context Management (2)

• checkpoint — Save state before /clear
• load_context — Restore from checkpoint or memories

✅ Checkpoint System (3)

• generateCheckpoint — Create bidirectional learning checkpoints
• loadCheckpoint — Resume from specific checkpoint
• adjustThreshold — Tune context compression

📊 Dashboard (4)

• view_dashboard — Real-time cost UI
• get_token_summary — Total tokens, cost, budget
• get_task_list — Tasks with cost breakdown
• get_optimization_alerts — Top 5 savings opportunities

📈 Reporting & Logging (4)

• generate_session_report — Detailed cost report
• get_agent_usage_log — All dispatches with timestamps
• log_agent_dispatch — Log a single dispatch
• get_agent_usage_summary — Usage by model

📊 Graphify Tools (6+)

• graph_query — Search concepts in knowledge graph
• graph_context — Get 360° view of a concept
• graph_communities — Find clusters and god nodes
• graph_analyze — Trigger graph analysis
• Plus: graph export, temporal queries, relationship mapping

💾 MemPalace Tools (29)

• search_memory — Semantic search across sessions
• add_memory — Save findings and discoveries
• recall_context — Load by wing/room/date
• wake_up — Auto-load session context
• create_wing — Organize by project
• create_room — Organize by topic
• Plus: 23 more tools for retrieval, indexing, exports, knowledge graphs

🔗 GitNexus Tools (via Ultraflow)

• gitnexus_query — Find code by concept
• gitnexus_context — Full symbol relationships
• gitnexus_impact — Blast radius analysis
• gitnexus_rename — Safe refactoring
• gitnexus_detect_changes — Pre-commit verification

🎛️ Configuration

User-Level Customization

Edit .ultraflow/config.json:

{
  "version": "1.3.1",
  "agent": "claude-code",
  "dashboard": {
    "port": 3001,
    "autoStart": true
  },
  "hooks": {
    "SessionStart": ["load-memories", "show-checkpoint"],
    "SessionEnd": ["consolidate-memories", "generate-report"]
  }
}

Environment Variables

PORT=3001 npx ultraflow start dashboard
DASHBOARD_URL=http://localhost:3001 npx ultraflow start brain
BRAIN_MEMORY_PATH=/custom/path npx ultraflow start

🌐 Supported AI Systems

| Agent | Detection | Integration | |-------|-----------|-------------| | Claude Code | .claude/settings.json | Full hooks + MCP | | OpenCode | .opencode/config.yaml | Full hooks + MCP | | Codex | .codex/config.toml | Full hooks + MCP | | OpenClaw | .openclaw/manifest.json | Full hooks + MCP |

Auto-detection runs on npx ultraflow init — no manual config needed.

📡 Dashboard API

The dashboard exposes a REST API for programmatic access:

# Health check
curl http://localhost:3000/api/health

# Cost summary
curl http://localhost:3000/api/summary
# { "totalTokens": 45230, "totalCost": "$1.24", "budget": "$5.00" }

# Optimization opportunities
curl http://localhost:3000/api/opportunities
# [ { "opportunity": "Use Haiku instead of Sonnet", "savings": "$0.42" }, ... ]

Real-time updates via WebSocket:

const ws = new WebSocket('ws://localhost:3000');
ws.on('message', (msg) => {
  const update = JSON.parse(msg);
  console.log(`Cost updated: $${update.totalCost}`);
});

📊 TokenTracker: Multi-Tool Token Tracking

TokenTracker automatically tracks token usage across 11 AI coding assistants (Claude Code, Cursor, Gemini, Codex, OpenCode, Kiro, OpenClaw, Every Code, Hermes Agent, GitHub Copilot, Kimi Code).

Quick Setup

# Install globally (one-time)
npm install -g tokentracker-cli

# Initialize and auto-detect tools
npx tokentracker-cli init --yes

# View dashboard
open http://localhost:7680  # Opens in browser

Features

• Local-first: All data stays on your machine—no account or API keys required
• Multi-tool: Automatically detects and tracks Claude Code, Gemini, Opencode, and more
• Real-time dashboard: Live token counts, cost trends, usage heatmaps at http://localhost:7680
• Native integration: Auto-installs hooks in Claude Code, Gemini, Opencode settings
• Privacy-focused: Only tracks token counts and timestamps—never prompts or responses
• Zero configuration: Once installed, tracking works automatically

Check Status

npx tokentracker-cli status

# Output:
# - Claude hooks: set ✓
# - Gemini hooks: set ✓
# - Opencode plugin: set ✓

Learn more: TokenTracker on GitHub

🔧 Integrated Power Tools

📊 Graphify: Knowledge Graphs for Code

Transform your codebase into queryable knowledge graphs with automatic relationship discovery:

# Auto-analyze codebase and generate graph
npx graphify analyze

# Query for concepts and relationships
npx graphify query "authentication flow"
npx graphify context "UserService" --depth 2

# Interactive explorer
npx graphify serve  # http://localhost:3000

Features:

• 25+ languages via tree-sitter AST
• Multimodal: code, docs, PDFs, images, video/audio
• Automatic analysis after git commits
• 29 EXTRACTED/INFERRED relationships with confidence scores
• 71.5x fewer tokens per query vs raw files

Learn more: .claude/skills/graphify/*/SKILL.md

💾 MemPalace: Persistent Conversation Memory

Store and retrieve conversation history locally with semantic search:

# Auto-loads on session start
mempalace wake-up

# Search across all sessions
mempalace search "performance optimization"

# Organize by project/topic
mempalace add "Implemented Redis caching" --wing MyProject --room Performance

Features:

• 29 MCP tools for full integration
• 96.6% R@5 retrieval accuracy (zero API calls)
• Hierarchical memory: Wings (projects) → Rooms (topics) → Drawers (content)
• Semantic search understands meaning, not just keywords
• Auto-indexes sessions for next-time context loading

Learn more: .claude/skills/mempalace/*/SKILL.md

🔗 GitNexus: Code Intelligence

Understand code relationships, assess impact before changes:

# Impact analysis before editing
npx gitnexus impact --target "UserService" --direction upstream

# Find execution flows
npx gitnexus query "authentication flow"

# Safe refactoring
npx gitnexus rename --symbol "oldName" --new-name "newName" --dry-run

Features:

• Execution flow analysis
• Impact radius before changes
• Safe multi-file refactoring
• Pre-commit verification

🚀 Advanced Usage

# Analyze and optimize
npx ultraflow lyra "your prompt here" -m detail

# Platform-specific versions
npx ultraflow lyra "your prompt" --versions
# Generates: claude, chatgpt, gemini, opencode, codex versions

# Analyze without optimizing
npx ultraflow lyra "your prompt" --analyze

npx ultraflow ruflo dispatch \
  --agent "claude-code" \
  --agent "opencode:nemotron" \
  --task "Analyze schema" \
  --task "Generate migrations"

# Monitor costs across agents
curl http://localhost:3000/api/usage

// Detect context degradation
const threshold = 2000; // tokens
if (contextTokens > threshold * 0.8) {
  await brain.generateCheckpoint({
    summary: 'Context approaching limit',
    nextSteps: 'Load fresh context in next session'
  });
}

// Adjust compression sensitivity
await brain.adjustThreshold({
  newThreshold: 1500,
  reason: 'Budget constraint this quarter'
});

📊 Architecture

┌──────────────────────────────────────────────────────────────┐
│  Your AI Agents (Claude Code/OpenCode/Codex/OpenClaw/Etc)   │
│         ↓ (MCP Server)                                        │
├──────────────────────────────────────────────────────────────┤
│  Ultraflow Core                                              │
│  ├─ Brain (semantic memory + search)                         │
│  ├─ DreamLord (context + checkpoints + costs)                │
│  ├─ Lyra (prompt optimization)                               │
│  ├─ Ruflo (multi-agent orchestration)                        │
│  ├─ GitNexus (code intelligence)                             │
│  ├─ Graphify (knowledge graphs)                              │
│  └─ MemPalace (conversation memory)                          │
├──────────────────────────────────────────────────────────────┤
│  ↓              ↓                ↓              ↓              ↓│
│ Memory DB   Dashboard       Code Index     Memory Graph   TokenTracker
│ (.claude/)  (3000)          (GitNexus)    (Graphify)     (port 7680)
│             (optimization)                + Conversation DB  multi-tool
│                                          (MemPalace)      token tracking
└──────────────────────────────────────────────────────────────┘

🎓 Quickstart Commands

| Task | Command | |------|---------| | Initialize | npx ultraflow init | | Start everything | npx ultraflow start | | Start just dashboard | npx ultraflow start dashboard | | Check status | npx ultraflow status | | Stop services | npx ultraflow stop | | Optimize prompt | npx ultraflow lyra "your prompt" | | View agent config | npx ultraflow register |

📦 Version

v1.3.1 — Stable

📄 License & Attribution

MIT © S-Nikk

Built with:

• TokenTracker for multi-tool token tracking
• GitNexus for code intelligence
• Ruflo for multi-agent orchestration
• OpenCode for cost-optimized AI routing

🤝 Support

• 📖 DETAILED_SUMMARY.md — Comprehensive feature guide
• 🔧 CLI Reference
• 📊 Dashboard

Get started in 30 seconds:

npm install -g @s-nikk/ultraflow && ultraflow init && ultraflow start

🙏 Acknowledgments

Ultraflow builds on top of exceptional open source projects:

• GitNexus — Code intelligence & execution flow analysis
• Ruflo — Multi-agent orchestration framework
• OpenCode — Open source AI model routing & delegation

These projects power Ultraflow's ability to understand code, coordinate agents, and reduce costs through intelligent task routing.