# Neuraltrace

> Browser memory for AI agents. Save anything you browse. Every AI remembers it. MCP-native.

- **Type:** MCP server
- **Install:** `agentstack add mcp-neuraltrace-ai-neuraltrace`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [NeuralTrace-AI](https://agentstack.voostack.com/s/neuraltrace-ai)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [NeuralTrace-AI](https://github.com/NeuralTrace-AI)
- **Source:** https://github.com/NeuralTrace-AI/neuraltrace
- **Website:** https://neuraltrace.ai/

## Install

```sh
agentstack add mcp-neuraltrace-ai-neuraltrace
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Capture anything you browse. Every AI remembers it.

  
  
  

---

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](https://modelcontextprotocol.io) (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](https://nodejs.org/)). Older versions will fail to compile `better-sqlite3`.
- **Docker** (optional, for containerized deployment)

## Quick Start

### Option 1: Docker (recommended)

```bash
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

```bash
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`:

| Provider | URL | API Key | Notes |
|----------|-----|---------|-------|
| Ollama (recommended) | `http://localhost:11434/v1` | Not needed | Free, local, private |
| OpenAI | `https://api.openai.com/v1` | Required | Cloud, paid |
| LocalAI | `http://localhost:8080/v1` | Not needed | Free, local |
| LM Studio | `http://localhost:1234/v1` | Not needed | Free, local |

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`):

```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

| Tool | Description |
|------|-------------|
| `add_trace` | Save a memory (content + tags) to your vault |
| `search_neuraltrace_memory` | Semantic search across your vault |
| `delete_trace` | Remove a memory by ID |

## 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`](.env.example) for all available options. Key settings:

| Variable | Required | Description |
|----------|----------|-------------|
| `ADMIN_PASSWORD` | Yes | Protects your vault — also used as Auth Token in the Chrome extension |
| `EMBEDDING_PROVIDER_URL` | No | OpenAI-compatible embedding endpoint (e.g. `http://localhost:11434/v1` for Ollama). If omitted, search uses keyword matching only. |
| `EMBEDDING_MODEL` | No | Embedding model name (e.g. `nomic-embed-text` for Ollama, `text-embedding-3-small` for OpenAI) |
| `EMBEDDING_API_KEY` | No | API key for the embedding provider. Not needed for Ollama/LocalAI/LM Studio. |
| `OPENAI_API_KEY` | No | Legacy option — if set and `EMBEDDING_PROVIDER_URL` is not, NeuralTrace auto-configures OpenAI embeddings. |
| `PORT` | No | Server port (default: 3000) |
| `NEURALTRACE_MODE` | No | `selfhosted` (default) or `cloud` |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and guidelines.

## Security

Found a vulnerability? See [SECURITY.md](SECURITY.md) for responsible disclosure.

## License

[Apache 2.0](LICENSE) — use it, modify it, ship it.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [NeuralTrace-AI](https://github.com/NeuralTrace-AI)
- **Source:** [NeuralTrace-AI/neuraltrace](https://github.com/NeuralTrace-AI/neuraltrace)
- **License:** Apache-2.0
- **Homepage:** https://neuraltrace.ai/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-neuraltrace-ai-neuraltrace
- Seller: https://agentstack.voostack.com/s/neuraltrace-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.