Neuraltrace

NeuralTrace is an open-source browser memory layer for AI agents. Save pages, notes, and context from your browser into a personal vault — then access it from any AI tool via MCP (Model Context Protocol).

The problem: Every AI tool starts from zero. You explain the same preferences, decisions, and context over and over — to ChatGPT, Claude, Gemini, Copilot. We call this the "Amnesia Tax."

The fix: Save it once in NeuralTrace, and every AI remembers it. Your vault connects to any MCP-compatible tool automatically.

Features

• Chrome Extension — Side panel AI chat with memory-powered responses. Save pages, summarize content, search your vault — all without leaving the browser.
• MCP Server — Dual transport (SSE + Streamable HTTP) works with Claude, ChatGPT, Cursor, VS Code, and any MCP client.
• Semantic Search — Find memories by meaning, not just keywords. Works with Ollama, OpenAI, LocalAI, LM Studio, or any OpenAI-compatible embedding provider.
• Quick Save — One-click page capture. No AI round-trip, sub-second saves.
• Background Enrichment — Saved pages are automatically classified with tags, dates, and locations.
• Local-First — Your data stays on your machine. SQLite vault, no cloud required.
• Self-Hosted — Run the full stack on your own hardware with Docker.

Prerequisites

• Node.js 18+ (LTS recommended — download). Older versions will fail to compile better-sqlite3.
• Docker (optional, for containerized deployment)

Quick Start

Option 1: Docker (recommended)

git clone https://github.com/NeuralTrace-AI/neuraltrace.git
cd neuraltrace
cp .env.example .env
# Edit .env — set ADMIN_PASSWORD (and optionally EMBEDDING_PROVIDER_URL for semantic search)
docker compose up -d

Server runs at http://localhost:3000. Health check: curl http://localhost:3000/health

Option 2: Run from source

git clone https://github.com/NeuralTrace-AI/neuraltrace.git
cd neuraltrace
npm install
cp .env.example .env
# Edit .env — set ADMIN_PASSWORD (and optionally EMBEDDING_PROVIDER_URL for semantic search)
npm run build
npm start

Load the Chrome Extension

1. Open chrome://extensions in Chrome or Edge
2. Enable Developer mode (top right)
3. Click Load unpacked and select the extension/ folder
4. Click the NeuralTrace icon to open the side panel
5. The extension defaults to Self-hosted mode with http://localhost:3000 — no config needed if your server is running locally
6. Open settings (gear icon) → enter your ADMIN_PASSWORD in the Auth Token field
7. Start chatting — use /save-page to save any page, /search to find memories

Embedding Providers

NeuralTrace supports any OpenAI-compatible embedding endpoint. Configure it in .env:

Set EMBEDDING_PROVIDER_URL and EMBEDDING_MODEL in your .env. If neither is set, search falls back to keyword matching. The legacy OPENAI_API_KEY variable still works for backwards compatibility — NeuralTrace will auto-configure OpenAI if it's present and EMBEDDING_PROVIDER_URL is not set.

Connect Your AI Tools

NeuralTrace speaks MCP, so any compatible tool can read and write to your vault.

Claude Code / Cursor / VS Code

Add to your MCP config (e.g., ~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "neuraltrace": {
      "url": "http://localhost:3000/sse"
    }
  }
}

Claude.ai / ChatGPT (OAuth)

Use http://localhost:3000/mcp as the server URL. NeuralTrace supports OAuth 2.1 with PKCE for web-based AI platforms.

MCP Tools

Architecture

Browser ──► Chrome Extension (side panel chat)
                    │
                    ▼
              NeuralTrace Server (Express.js)
              ├── MCP Transport (SSE + Streamable HTTP)
              ├── REST API (auth, proxy, billing)
              ├── SQLite Vault (per-user)
              └── Embeddings (Ollama, OpenAI, LocalAI, etc.)
                    │
                    ▼
        Claude / ChatGPT / Cursor / any MCP client

Configuration

See .env.example for all available options. Key settings:

Contributing

See CONTRIBUTING.md for setup instructions and guidelines.

Security

Found a vulnerability? See SECURITY.md for responsible disclosure.

License

Apache 2.0 — use it, modify it, ship it.