LatentContext MCP Server

A session-scoped memory layer for LLMs, built on the Model Context Protocol. LatentContext gives AI assistants the ability to explicitly store and retrieve notes, decisions, and context within a single conversation — keeping the AI focused on the current task without cross-session data contamination.

Why LatentContext?

LLM context windows are large but finite. In long conversations the assistant loses track of earlier decisions, forgets what files it already edited, and repeats work. LatentContext solves this by providing a structured, strictly session-isolated scratchpad:

• Session Isolation — every conversation starts from a completely clean slate. Data from a previous project or conversation can never leak into the current one.
• Explicit Memory — the assistant actively stores detailed notes about what it did, why, and how. This replaces vague "I think we did X" with retrievable, concrete records.
• Quality Enforcement — the server rejects overly terse entries (fewer than 10 words) and warns about brief ones (under 25 words), forcing the assistant to write useful context rather than throwaway one-liners.
• Token-Budgeted Retrieval — when retrieving context, results are ranked, deduplicated, and trimmed to fit within a configurable token budget so the assistant's context window isn't flooded.
• Compression — when working memory grows large during a long session, it can be compressed into a summary, preserving the important details while freeing up space.

Quick Start

# Clone and install
git clone https://github.com/Master0fFate/LatentContext-MCP.git
cd LatentContext-MCP
npm install

# Build
npm run build

# Run (usually launched automatically by the MCP host)
npm start

Requirements: Node.js 18+. No API keys needed — everything runs locally.

MCP Host Configuration

Add to your MCP host settings (Claude Desktop, Cursor, Antigravity, etc.):

{
  "mcpServers": {
    "latentcontext": {
      "command": "node",
      "args": ["/absolute/path/to/LatentContext-MCP/dist/index.js"]
    }
  }
}

Restart the MCP host after saving. The server communicates over stdin/stdout using the MCP JSON-RPC protocol.

Tools

How It Works

Session Lifecycle

1. session_start        → Fresh session with unique ID, zero entries
2. memory_store (×N)    → AI saves detailed notes as it works
3. memory_retrieve      → AI recalls what it stored earlier
4. memory_compress      → (optional) Compress when memory grows large

Session Isolation Model

Each session_start call:

1. Generates a timestamp-prefixed UUID (e.g., 1740567150290-ec459108-2bf4-...) for guaranteed uniqueness.
2. Clears the entire in-memory working buffer.
3. Returns a clean slate — memory_retrieve will return nothing until memory_store is called.

What's included in retrieval:

• Tier 0 (Working Memory) — entries stored via memory_store during this session.
• Tier 1 (Session Notes) — compressed summaries created by memory_compress during this session.

What's excluded from retrieval:

• Data from any other session (past or concurrent).
• Global knowledge graph entities and relations.
• Global vector store search results.
• Core/epoch tier data from previous sessions.

This guarantees that a banking dashboard project won't pull in data from an audio visualizer project, even if they share the same database file.

Content Quality Enforcement

The server enforces minimum quality on stored memories:

This prevents the common failure mode where the AI stores useless entries like "Fixed the bug" instead of "Fixed a null pointer in the UserService.getProfile() method caused by missing null check on the database result. Added Optional<User> return type and a fallback to guest profile when the user record doesn't exist.".

Memory Tiers

Tier 0 (Working):   In-memory buffer of entries from the current session.
                     Auto-compresses when token count exceeds threshold (~20K tokens).

Tier 1 (Session):   Compressed summaries of overflowed working memory (up to ~4K tokens each).
                     Created automatically or via memory_compress scope='working'.

Architecture

src/
├── index.ts              # Entry point, stdio transport, console suppression, graceful shutdown
├── server.ts             # MCP tool/resource/prompt definitions and handlers
├── config.ts             # Configuration loader with deep-merge defaults
├── database.ts           # SQLite (via sql.js WASM) schema, CRUD operations
├── session.ts            # Session lifecycle (start, end, ID generation)
├── memory-manager.ts     # Store, compress, forget, and status operations
├── context-assembler.ts  # Retrieval algorithm: ranking, dedup, budget-filling
├── knowledge-graph.ts    # Entity-relation triple store (internal, not exposed as a tool)
├── vector-store.ts       # Embedding-based semantic search (internal)
├── embeddings.ts         # Local embeddings via @huggingface/transformers (ONNX)
├── token-counter.ts      # Token counting and truncation (js-tiktoken)
└── sql.js.d.ts           # Type declarations for sql.js

Key Dependencies

Platform Notes (Windows)

• The server automatically hides its console window ~1-2 seconds after startup using the Win32 API (GetConsoleWindow + ShowWindow). Do not manually close the Node.js window — it is the running server process.
• All console.*, stray stdout, and stderr output is redirected to server.log in LatentContext's dedicated data directory to prevent stdio corruption of the MCP JSON-RPC protocol.
• The sql.js WASM binary is explicitly resolved via createRequire to handle Windows path resolution edge cases.

Configuration

LatentContext intentionally does not store data in the project opened by your IDE. By default, it uses a dedicated per-user data directory:

To override the location, set environment variables in your MCP host configuration:

You can place latentcontext.config.json in the dedicated data directory, pass it with LATENTCONTEXT_CONFIG, or place it beside the installed package. Relative storage.dataDir values are resolved relative to the config file, not the opened IDE project.

{
  "storage": {
    "dataDir": "C:/Users/you/AppData/Local/LatentContext-MCP",
    "sqliteFile": "memory.db"
  },
  "embedding": {
    "provider": "local",
    "model": "Xenova/all-MiniLM-L6-v2",
    "dimensions": 384
  },
  "tokenBudgets": {
    "defaultRetrieveBudget": 8000,
    "tier0Working": 16000,
    "tier1Session": 4000
  },
  "compression": {
    "tier0OverflowThreshold": 20000
  },
  "session": {
    "autoStartOnBoot": true
  }
}

Set "provider": "none" to disable embeddings entirely (vector indexing will be skipped).

Data Storage

All data is stored locally in the dedicated data directory as memory.db (SQLite via WASM). Runtime diagnostics are written to server.log in the same directory. No data leaves your machine. The database contains tables for entities, relations, summaries (tiered), vectors (embeddings), access logs, and sessions.

Resources

Prompts

Development

# Build
npm run build

# Dev mode (tsx, auto-recompile)
npm run dev

# Run diagnostic tests
node test-mcp.mjs

License

MIT