---
slug: "titan-memory-mcp-server"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/henryhawke/mcp-titan@main/README.md"
repo: "https://github.com/henryhawke/mcp-titan"
source_file: "README.md"
branch: "main"
---
# TITAN Memory: AI That Remembers Like You Do

I've kind of given up on this as I don't have money to train it. Feel free to submit any sort of pull requests :)

**Turn any AI into a learning companion that remembers across conversations**

[![npm version](https://badge.fury.io/js/@henryhawke%2Fmcp-titan.svg)](https://www.npmjs.com/package/@henryhawke/mcp-titan)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-22%2B-green)](https://nodejs.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## What is MCP-TITAN??

Think about how **you** remember things:
- 💭 **Short-term memory** - What you heard 5 seconds ago
- 📝 **Long-term memory** - Important facts you recall later
- 🗄️ **Deep storage** - Things you "just know" from years ago

**HOPE** (Hierarchical Online Persistent Encoding) is the second generation of TITAN and gives AI this same ability. Instead of forgetting everything after each conversation, it builds up knowledge like a human brain.

### The Problem HOPE Solves

```
❌ Standard AI (e.g., ChatGPT without plugins):
User: "I'm working on a React project with TypeScript"
AI: *Helps with code*
[Next session]
User: "How do I add a new component to my project?"
AI: "What framework are you using?" ← Forgot everything!

✅ HOPE Memory:
User: "I'm working on a React project with TypeScript"
HOPE: *Stores in long-term memory: React + TypeScript project*
[Next session]
User: "How do I add a new component?"
HOPE: *Recalls context* → "Here's a TypeScript React component for your project..."
```

---

## Key Features

### 🧠 **Three-Tier Memory System**
Like your brain, HOPE has multiple memory levels:

| Memory Level | What It Stores | How Long | Like Your Brain |
|--------------|----------------|----------|------------------|
| **Short-term** | Current conversation | Minutes | Working memory - what you just heard |
| **Long-term** | Important patterns | Days/weeks | Consolidated facts - things you studied |
| **Archive** | Core knowledge | Permanent | Deep knowledge - things you "just know" |

**Example:**
```
Conversation: "My dog Max is 3 years old and loves fetch"

HOPE storage:
- Short-term: "User talking about Max right now"
- Long-term: "User has dog named Max, age 3" (promoted after repeated mentions)
- Archive: "User is pet owner" (core fact, rarely changes)
```

### 🎯 **Smart Forgetting**
Not everything deserves to be remembered!

- **Surprising/novel information** → Stored longer
- **Repeated boring stuff** → Forgotten faster
- **Important patterns** → Promoted to long-term storage

This prevents memory bloat and focuses on what matters.

### 📈 **Continuous Learning** (Momentum-Based)
Unlike standard AI that's frozen after training:

```
Standard AI: Learn once → Deploy → Never changes
HOPE: Learn → Deploy → Keep learning from every interaction
```

**How it works:**
- Sees pattern once → Small memory trace
- Sees pattern repeatedly → Stronger reinforcement
- Contradictory information → Gradual update (not catastrophic overwrite)

This is called **momentum learning** - changes happen smoothly, preventing the AI from "unlearning" important things.

### 🔗 **Sequence Understanding** (Token Flow)
HOPE understands **sequences**, not just individual facts:

```
❌ Standard: Knows "cat", "sat", "mat" as separate words
✅ HOPE: Understands "cat sat on mat" as a pattern

User: "The cat..."
HOPE: *Predicts "sat on mat"* (learned sequence)
```

### 📊 **Surprise-Based Attention**
HOPE pays attention to what's unexpected:

```
Input: "The sky is blue"
HOPE: Low surprise → Process quickly, minimal storage

Input: "The sky is green with purple clouds"
HOPE: High surprise! → Deep processing, strong memory trace
```

---

## How It Works (Technical Overview)

### The HOPE Architecture

HOPE is based on cutting-edge research in **Nested Learning** - the idea that learning happens at multiple levels simultaneously:

```
┌─────────────────────────────────────┐
│  INPUT: "Help me debug this code"  │
└──────────────┬──────────────────────┘
               │
        ┌──────▼─────────┐
        │  Memory Router  │  ← Decides where to look
        │  (Surprise-based)│
        └──────┬──────────┘
               │
    ┌──────────┼──────────┐
    │          │          │
 ┌──▼─┐    ┌──▼─┐    ┌──▼─┐
 │Short│    │Long│    │Arch│  ← Three memory tiers
 │Term │    │Term│    │ive │
 └──┬─┘    └──┬─┘    └──┬─┘
    │          │          │
    └──────────┼──────────┘
               │
        ┌──────▼─────────┐
        │ Retentive Core  │  ← Processes & integrates
        │ (Sequence Model)│
        └──────┬──────────┘
               │
        ┌──────▼─────────┐
        │  Momentum       │  ← Smooth learning
        │  + Forgetting   │
        └──────┬──────────┘
               │
        ┌──────▼─────────┐
        │  OUTPUT         │
        │  + Memory Update│
        └─────────────────┘
```

### Core Mechanisms

1. **Continuum Memory System (CMS)**
   - Multi-tier storage with automatic promotion/demotion
   - Memories move between tiers based on access patterns and surprise

2. **Momentum-Based Updates** (from research paper)
   ```
   M_t = (1 - α) * M_t + S_t

   Where:
   - M_t = Memory at time t
   - α = Forgetting gate (higher for boring stuff)
   - S_t = Momentum term (accumulated learning)
   ```

3. **Selective State-Space Filters** (Mamba-style)
   - Efficient sequence processing
   - Adaptive filtering based on context

4. **Sparse Routing**
   - Not all memories are checked for every query
   - Routes queries to relevant memory tiers

---

## Installation & Setup

### Requirements
- **Node.js 22+** (required for TensorFlow.js optimizations)
- npm or bun package manager

### Quick Start

```bash
# Install
npm install @henryhawke/mcp-titan

# Or with bun
bun add @henryhawke/mcp-titan
```

### Configuration for Cursor

Add to `~/.cursor/settings.json`:

```json
{
  "mcp": {
    "servers": {
      "hope-memory": {
        "command": "npx",
        "args": ["-y", "@henryhawke/mcp-titan"],
        "workingDirectory": "/path/to/your/memory/storage"
      }
    }
  }
}
```

### Configuration for Claude Desktop

1. Open Claude Desktop settings
2. Add MCP server:
   - **Name:** hope-memory
   - **Command:** `npx`
   - **Args:** `-y @henryhawke/mcp-titan`
   - **Working Directory:** Where you want memories stored (default: `~/.hope_memory`)

### First Run

```bash
# Start the HOPE server
npx @henryhawke/mcp-titan

# The server will:
# 1. Create ~/.hope_memory/ directory
# 2. Initialize empty memory banks
# 3. Start listening for MCP tool calls
```

---

## Operational Quickstart

1) Run server: `bun run build && bun start` (or `npx @henryhawke/mcp-titan`)
2) Initialize tools in order:
   - `init_model`
   - `init_tokenizer`
   - `start_learner`
3) Store and recall:
   - Store: `store_memory { text, type?: episodic|semantic }`
   - Recall: `recall { query, topK? }`
   - Distill: `distill_memories { memories: number[][] }`
4) Online learning:
   - Add data: `enqueue_samples` (batch of input/target pairs, optional positive/negative)
   - Status: `learner_status`
   - Control: `start_learner`, `pause_learner`, `stop_learner`
5) Checkpoints:
   - Save: `save_checkpoint { path }`
   - Auto-export: `export_checkpoint` → `.hope_memory/checkpoints`
   - Import: `import_checkpoint { filename }` or `load_checkpoint { path }`
6) Health:
   - `health_check --detailed`
   - `get_hierarchical_metrics`, `get_momentum_metrics`, `get_token_flow_metrics`
7) Safety defaults:
   - Inputs sanitized and length-capped; arrays validated; paths sandboxed
   - URL bootstrap uses timeouts/size guards
   - Logs are structured, rotated, redacted

## Dumbed Down Getting Started

1) `bun run build && bun start`
2) Call `init_model`, then `init_tokenizer`, then `start_learner`
3) `store_memory` to save facts; `recall` to fetch them
4) `enqueue_samples` to teach; watch `learner_status`
5) `export_checkpoint` to back up; `import_checkpoint` to restore
6) If stuck: `health_check --detailed`

## Backward Compatibility

- Titan aliases are still exported (e.g., `TitanMemoryModel` → HOPE)
- Checkpoints include version + checksum and validate dimensions on load

---

## Usage Examples

### Basic Memory Operations

```typescript
// In your AI chat interface (Claude, Cursor, etc.)

// 1. Initialize memory (first time)
> init_model

// 2. Store some context
> bootstrap_memory text="I'm building a Python web app with FastAPI and PostgreSQL"

// 3. Have conversations - HOPE learns automatically
> help me set up database migrations
[HOPE stores: User uses FastAPI + PostgreSQL]

> how do I add authentication?
[HOPE recalls context: FastAPI project → suggests FastAPI-specific auth]

// 4. Check what's stored
> get_memory_state

// 5. Save for later
> save_checkpoint path="my_project_memory.json"
```

### Training HOPE

```typescript
// Explicit training on patterns
> train_step
  x_t: "def hello"
  x_next: "world"

// HOPE learns: "def hello" → "world" pattern

// Later:
> forward_pass input="def hello"
// Predicts: "world" (or similar completion)
```

### Online Learning Mode

```typescript
// Start continuous learning
> init_learner

// Feed training samples as you work
> add_training_sample data="function add(a, b) { return a + b; }"

// HOPE learns in background, memory updates automatically

// Check learning progress
> get_learner_stats
```

---

## Available MCP Tools

HOPE exposes **19 tools** via the Model Context Protocol:

### Memory Management
- `init_model` - Initialize or reconfigure memory system
- `bootstrap_memory` - Quick-load context from text or URL
- `get_memory_state` - Inspect current memory contents
- `memory_stats` - Get statistical summary
- `prune_memory` - Clean up low-value memories

### Learning Operations
- `forward_pass` - Query memory and get prediction
- `train_step` - Explicit learning from example pair
- `reset_gradients` - Clear training state

### Persistence
- `save_checkpoint` - Save memory to file
- `load_checkpoint` - Restore from checkpoint

### Online Learning
- `init_learner` - Start background learning service
- `pause_learner` / `resume_learner` - Control learning
- `get_learner_stats` - Monitor learning metrics
- `add_training_sample` - Feed training data

### Advanced Metrics
- `get_token_flow_metrics` - Sequence pattern analysis
- `get_hierarchical_metrics` - Memory tier distribution
- `health_check` - System health & performance

### Utilities
- `help` - List all available tools with descriptions

See [docs/api/README.md](https://github.com/henryhawke/mcp-titan/blob/HEAD/docs/api/README.md) for complete API reference.

---

## Real-World Use Cases

### 1. **Personalized Code Assistant**

```
Day 1: "I'm learning Rust"
HOPE: Stores preference for Rust

Day 5: "Show me how to handle errors"
HOPE: Recalls Rust context → Shows Result<T, E> pattern
      (Not Python try/catch or JavaScript throw)
```

### 2. **Project Context Memory**

```
Store once: "Working on e-commerce site, React frontend, Django backend, Stripe payments"

Every question after:
- "Add a new product page" → HOPE knows React + Django + ecommerce context
- "How do I refund a payment" → HOPE knows you use Stripe
- "Deploy to production" → HOPE remembers full stack (React + Django)
```

### 3. **Research Assistant**

```
Feed HOPE 50 research papers on neural networks

Query: "What's the consensus on attention mechanisms?"
HOPE:
- Short-term: Current paper's view
- Long-term: Cross-paper patterns identified
- Archive: Fundamental concepts
→ Synthesized answer from all levels
```

### 4. **Continuous Learning Chatbot**

```
Traditional bot:
- User: "No, I meant X not Y"
- Bot: "OK" → Forgets next session

HOPE bot:
- User: "No, I meant X not Y"
- HOPE: Stores correction in long-term memory
- Next session: Remembers correction automatically
```

---

## Performance & Scalability

### Benchmarks

| Metric | Performance |
|--------|-------------|
| Memory initialization | ~100ms |
| Forward pass (query) | <50ms (95th percentile) |
| Training step | ~75ms |
| Checkpoint save/load | ~200ms for 10K memories |
| Memory footprint | ~500MB for typical usage |

### Capacity

- **Short-term:** 64 slots (fast access)
- **Long-term:** 256 slots (medium access)
- **Archive:** 512 slots (stable storage)
- **Total:** ~800 distinct memory traces

Memories automatically promoted/demoted based on:
- Access frequency
- Surprise value
- Temporal recency

---

## Architecture Deep Dive

For technical users interested in the implementation:

### Research Foundation

HOPE implements concepts from:
- **Nested Learning** - Multi-level optimization problems
- **Continuum Memory Systems** - Multi-tier storage with different update frequencies
- **Retentive Networks** - Efficient sequence modeling
- **Selective State-Space Models** (Mamba) - Adaptive filtering

See [HOPE.md](https://github.com/henryhawke/mcp-titan/blob/HEAD/HOPE.md) for the full research paper.

### Key Components

```
src/hope_model/
├── index.ts              # Main HopeMemoryModel class
├── continuum_memory.ts   # Three-tier memory management
├── retention_core.ts     # Sequence processing
├── memory_router.ts      # Surprise-based routing
├── mamba_filters.ts      # Selective state-space filters
└── optimizer_hooks.ts    # Delta compression, layer scheduling
```

### Memory State Structure

```typescript
interface HopeMemoryState {
  shortTerm: Tensor2D;       // Recent activations [N, 256]
  longTerm: Tensor2D;        // Consolidated patterns [M, 256]
  archive: Tensor2D;         // Stable knowledge [K, 256]

  surpriseHistory: Tensor1D; // Surprise scores over time
  accessCounts: Tensor1D;    // How often each memory accessed
  timestamps: Tensor1D;      // When each memory created

  // HOPE-specific enhancements
  momentumState?: Tensor2D;  // Momentum for smooth learning
  tokenFlowHistory?: number[][]; // Sequence patterns
  levelIndex: Tensor1D;      // Which tier each memory belongs to
}
```

---

## Development

### Build from Source

```bash
git clone https://github.com/henryhawke/mcp-titan.git
cd mcp-titan

# Install dependencies
bun install  # or npm install

# Build
bun run build

# Test
bun test

# Run locally
bun start
```

### Project Structure

```
mcp-titan/
├── src/
│   ├── hope_model/          # Core HOPE architecture
│   ├── tokenizer/           # BPE tokenization & embeddings
│   ├── training/            # Training pipeline
│   ├── index.ts             # MCP server entry point
│   └── types.ts             # TypeScript interfaces
├── docs/
│   ├── api/                 # API documentation
│   ├── architecture-overview.md
│   └── typescript-error-resolution-guide.md
├── test/                    # Test suites
├── HOPE.md                  # Research paper
├── PLAN.md                  # Implementation roadmap
└── README.md                # This file
```

### Running Tests

```bash
# All tests
bun test

# With coverage
bun test --coverage

# Specific test file
bun test src/__tests__/hope_model.test.ts
```

---

## Roadmap

### ✅ Implemented (v3.0)
- [x] Three-tier continuum memory system
- [x] Retentive sequence processing
- [x] Selective state-space filters
- [x] Memory routing with surprise detection
- [x] Hierarchical promotion/demotion
- [x] MCP server with 19 tools
- [x] Checkpoint save/load
- [x] Online learning service

### 🚧 In Progress (v3.1)
- [ ] Fix TypeScript compilation errors (42 → 0)
- [ ] Implement momentum-based updates (Equations 32-33)
- [ ] Activate forgetting gate mechanism
- [ ] Token flow tracking

### 🔮 Planned (v4.0)
- [ ] Deep neural memory module (MLP-based)
- [ ] Self-modifying learning
- [ ] Multi-modal memory (text + code + images)
- [ ] Distributed memory across multiple servers
- [ ] Fine-grained access control

See [PLAN.md](https://github.com/henryhawke/mcp-titan/blob/HEAD/PLAN.md) for detailed implementation plan.

---

## Troubleshooting

### "Module not found" errors

```bash
# Ensure Node.js 22+
node --version

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install
```

### Memory leaks during long sessions

```typescript
// HOPE has automatic cleanup, but you can manually trigger:
> reset_gradients
> prune_memory threshold=0.1
```

### TypeScript compilation errors

Current known issue (being fixed in v3.1). To use despite errors:

```bash
# Skip type checking
npm run build --skipTypeCheck

# Or use published version
npx @henryhawke/mcp-titan
```

### Slow performance

```typescript
// Reduce memory capacity in config
> init_model config={
  "shortTermSlots": 32,  // Default 64
  "longTermSlots": 128,  // Default 256
  "archiveSlots": 256    // Default 512
}
```

---

## Contributing

Contributions welcome! Areas needing help:

1. **Fixing TypeScript errors** - See `docs/typescript-error-resolution-guide.md`
2. **Implementing momentum updates** - See `PLAN.md` Phase 1, Task 1.1
3. **Documentation improvements** - Make HOPE more accessible
4. **Test coverage** - Current ~60%, target 80%+

### Development Workflow

1. Fork the repo
2. Create feature branch: `git checkout -b feature/amazing-feature`
3. Make changes and test: `bun test`
4. Commit: `git commit -m 'Add amazing feature'`
5. Push: `git push origin feature/amazing-feature`
6. Open Pull Request

See [CONTRIBUTING.md](https://github.com/henryhawke/mcp-titan/blob/HEAD/CONTRIBUTING.md) for detailed guidelines.

---

## Research & Citations

If you use HOPE in research, please cite:

```bibtex
@article{behrouz2025nested,
  title={Nested Learning: The Illusion of Deep Learning Architectures},
  author={Behrouz, Ali and Razaviyayn, Meisam and Zhong, Peiling and Mirrokni, Vahab},
  journal={NeurIPS},
  year={2025}
}
```

### Related Work

- **Transformer-XL** - Segmented recurrence for long sequences
- **Retentive Networks** - Efficient alternatives to attention
- **Mamba** - Selective state-space models
- **Test-Time Training (TTT)** - Online learning in neural networks
- **Fast Weight Programmers** - Dynamic weight updates

---

## License

MIT License - See [LICENSE](https://github.com/henryhawke/mcp-titan/tree/HEAD/LICENSE) file

---

## Support & Community

- **Issues:** [GitHub Issues](https://github.com/henryhawke/mcp-titan/issues)
- **Discussions:** [GitHub Discussions](https://github.com/henryhawke/mcp-titan/discussions)
- **Documentation:** [docs/](https://github.com/henryhawke/mcp-titan/tree/HEAD/docs/)
- **Email:** support@henryhawke.dev

---

## FAQ

### Q: How is this different from RAG (Retrieval-Augmented Generation)?

**A:** RAG fetches external documents; HOPE builds internal neural memory.

| Feature | RAG | HOPE |
|---------|-----|------|
| Storage | External vector DB | Internal neural tensors |
| Learning | No learning (just retrieval) | Continuous learning with momentum |
| Forgetting | Never forgets (stores all) | Smart forgetting (prunes low-value) |
| Context | Retrieved documents | Learned patterns |
| Speed | Slower (external lookup) | Faster (in-memory) |

### Q: Does HOPE replace fine-tuning?

**A:** No, complementary. Fine-tuning = pre-training knowledge. HOPE = session-specific learning.

```
Base Model → Fine-tuning → HOPE Learning
(General)    (Domain)      (User-specific)
```

### Q: How much memory does HOPE use?

**A:** ~500MB typical, configurable. Reduce by lowering tier capacities.

### Q: Can HOPE run on CPU?

**A:** Yes! Uses TensorFlow.js Node backend (CPU). GPU optional but not required.

### Q: Is my data private?

**A:** Yes. HOPE runs locally, memories stored on your disk (`~/.hope_memory`). No cloud upload.

---

**Made with ❤️ by the HOPE team**

*Turn your AI into a learning companion that grows with you.*