Skip to content
Back to search

ArcRift

Persistent local memory layer for AI. ArcRift uses a extension and a native MCP server to sync context and decisions from your browser chats (Claude, ChatGPT, DeepSeek) straight to your local IDE agents (Cursor, Claude Code, Windsurf) powered by a local SQLite knowledge graph.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/eshaan-nair--arcrift/badge.svg)](/listings/eshaan-nair--arcrift)

HTML

<a href="/listings/eshaan-nair--arcrift"><img src="/api/listings/eshaan-nair--arcrift/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

For Users (The Easy Way)

> [!IMPORTANT] > ArcRift is a powerful AI developer tool. Before installing the `.exe`, you must have [Node.js](https://nodejs.org/) and [Ollama](https://ollama.com/) installed on your computer to run the backend and local AI models. If you don't have these, use the *Developer (One-Command Setup)* below to automatically install them!

1. Head over to the [Releases](https://github.com/Eshaan-Nair/ArcRift/releases) page. 2. Download the latest `ArcRift_Installer.exe` (or your OS equivalent). 3. Double-click the installer to install ArcRift on your machine. 4. Launch ArcRift from your Start menu! The app will live entirely in your system tray and run seamlessly in the background.

For Developers (Building from Source)

If you want to modify the code, build the project yourself, or use the MCP Tools:

**1. One-Command Setup (All Platforms)**

npx arcrift-setup
copy .env.example .env

This clones the repo, checks dependencies, pulls Ollama models, installs packages, builds the backend, and sets up the env file.

**2. Launching the Development Server** To launch the native desktop application in dev mode:

npm run dev:desktop

or

cd dashboard
npm run dev
cd backend
npm run dev

This will start the backend seamlessly in the background and open the native ArcRift dashboard. When you close the window, it will minimize to your system tray. You can fully quit ArcRift from the tray menu.

Web Extension Setup

The extension requires the ArcRift backend to be running. If you have the **ArcRift Desktop App** running in your system tray, you are already good to go!

**Step 1 — Install the Extension**

**For Google Chrome / Edge / Brave:** 1. Download the Chrome `.zip` file from the [GitHub Releases](https://github.com/Eshaan-Nair/ArcRift/releases) page. 2. Extract the `.zip` file to a permanent folder on your computer. 3. Open `chrome://extensions` 4. Enable **Developer mode** (top-right toggle) 5. Click **Load unpacked** and select the folder you just extracted. 6. The ArcRift icon will appear in your toolbar!

**For Mozilla Firefox:** 1. Download the officially signed `.xpi` file from the [GitHub Releases](https://github.com/Eshaan-Nair/ArcRift/releases) page. 2. Simply **drag and drop** the `.xpi` file directly into your open Firefox window. 3. Click **Add** when prompted. It will be installed permanently!

**Step 2 — Use it**

Navigate to Claude, ChatGPT, Gemini, DeepSeek, Grok, Copilot, or Mistral. Click the ArcRift popup, enter a project name, and click **Save Chat**. Auto-connect activates immediately.

---

MCP Server Setup

The MCP server runs as a separate process and communicates with AI coding tools over stdio. The backend does **not** need to be running as an HTTP server — the MCP server initializes its own storage connection.

**Step 1 — Build the backend**

cd backend
npm install
npm run build

This produces `backend/dist/mcp/server.js`.

**Step 2 — Generate your config (easiest)**

cd backend
npm run mcp:config

This prints a pre-formatted JSON block with absolute paths resolved for your machine. Copy it directly into your tool's config file.

**Step 3 — Add to your AI tool**

**Claude Desktop** — `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/.claude/claude_desktop_config.json` (macOS):

{
  "mcpServers": {
    "arcrift": {
      "command": "node",
      "args": ["C:/path/to/ARCRIFT/backend/dist/mcp/server.js"]
    }
  }
}

**Claude Code** — run in your project directory:

claude mcp add ArcRift node /path/to/ARCRIFT/backend/dist/mcp/server.js

**Cursor** — create `.cursor/mcp.json` in your project root:

{
  "mcpServers": {
    "arcrift": {
      "command": "node",
      "args": ["/path/to/ARCRIFT/backend/dist/mcp/server.js"]
    }
  }
}

**Windsurf** — create `.windsurf/mcp.json` in your project root:

{
  "mcpServers": {
    "arcrift": {

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 715 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # ArcRift — Persistent Memory for AI Coding Tools
  3. ### Your AI forgets everything between sessions. ArcRift fixes that.
  4. ### Memory saved in a browser chat is instantly available in your coding tool, and vice versa.
  5. **A local-first memory layer that captures your conversations, builds a searchable knowledge graph, and automatically injects the right context into every new prompt — no cloud, no subscriptions, no re-explaining yourself.**
  6. <br/>
  7. [![Stars](https://img.shields.io/github/stars/Eshaan-Nair/ARCRIFT?style=for-the-badge&logo=github&labelColor=0B0E14&color=6366F1)](https://github.com/Eshaan-Nair/ARCRIFT/stargazers)
  8. [![Forks](https://img.shields.io/github/forks/Eshaan-Nair/ARCRIFT?style=for-the-badge&logo=github&labelColor=0B0E14&color=06B6D4)](https://github.com/Eshaan-Nair/ARCRIFT/forks)
  9. [![Issues](https://img.shields.io/github/issues/Eshaan-Nair/ARCRIFT?style=for-the-badge&logo=github&labelColor=0B0E14&color=02C39A)](https://github.com/Eshaan-Nair/ARCRIFT/issues)
  10. [![Version](https://img.shields.io/badge/version-1.6.3-6366F1?style=for-the-badge&labelColor=0B0E14)](CHANGELOG.md)
  11. [![License: MIT](https://img.shields.io/badge/License-MIT-F8FAFC?style=for-the-badge&labelColor=0B0E14)](LICENSE)
  12. <br/>
  13. **Browser Extension:** Claude · ChatGPT · Gemini · DeepSeek · Grok · Copilot · Mistral
  14. **MCP (AI Coding Tools):** Claude Code · Cursor · Windsurf · Claude Desktop
  15. https://github.com/user-attachments/assets/f77a865a-cee9-4f7c-b0fa-4fb4d1cee7be
  16. [Youtube Link](https://www.youtube.com/watch?v=58zbSxzQ94U)
  17. The Demo only showcases the main function of ArcRift, there are a lot of features for you to Explore!
  18. <br/>
  19. </div>
  20. ## One Command Setup
  21. ```bash
  22. npx arcrift-setup
  23. ```
  24. <details>
  25. <summary><b>Historical NPM Downloads (Legacy Brands)</b></summary>
  26. <br/>
  27. Due to rebranding, the total historical download count is split across our three NPM packages:
  28. | Package Name | Downloads |
  29. |---|---|
  30. | **`arcrift-setup`** (Current) | [![Downloads](https://img.shields.io/npm/dt/arcrift-setup?style=flat-square&color=CB3837)](https://www.npmjs.com/package/arcrift-setup) |
  31. | **`glia-ai-setup`** (Legacy) | [![Downloads](https://img.shields.io/npm/dt/glia-ai-setup?style=flat-square&color=555555)](https://www.npmjs.com/package/glia-ai-setup) |
  32. | **`synq-setup`** (Legacy) | [![Downloads](https://img.shields.io/npm/dt/synq-setup?style=flat-square&color=555555)](https://www.npmjs.com/package/synq-setup) |
  33. </details>
  34. ---
  35. ## The Problem
  36. You are deep in a complex project. You have had 30 conversations with Claude about your auth flow, database schema, and deployment strategy. You open a new chat — and it is all gone. You spend 10 minutes re-explaining context you have already covered, and the AI gives you advice that contradicts decisions you made two weeks ago.
  37. ArcRift stops the cycle. It captures your AI conversations, extracts structured facts into a knowledge graph, embeds them as searchable vectors, and automatically prepends the most relevant context to every new prompt — before you even finish typing.
  38. ---
  39. ## Table of Contents
  40. - [One Command Setup](#one-command-setup)
  41. - [The Problem](#the-problem)
  42. - [Installation](#installation)
  43. - [Web Extension Setup](#web-extension-setup)
  44. - [MCP Server Setup](#mcp-server-setup)
  45. - [Running Both Together](#running-both-together)
  46. - [Usage Guide](#usage-guide)
  47. - [Using the Browser Extension](#using-the-browser-extension)
  48. - [Using the MCP Tools](#using-the-mcp-tools)
  49. - [Dashboard](#dashboard)
  50. - [System Requirements](#system-requirements)
  51. - [Key Features](#key-features)
  52. - [Architecture](#architecture)
  53. - [Quality-of-Life Details](#quality-of-life-details)
  54. - [How It Works](#how-it-works)
  55. - [How the Two Modes Work](#how-the-two-modes-work)
  56. - [Performance Benchmarks](#performance-benchmarks)
  57. - [Privacy and Security](#privacy-and-security)
  58. - [Comparison with Alternatives](#comparison-with-alternatives)
  59. - [What's New in v1.6.3](#whats-new-in-v162)
  60. - [Documentation](#documentation)
  61. - [Contributing](#contributing)
  62. - [License](#license)
  63. ---
  64. ## Installation
  65. ### For Users (The Easy Way)
  66. > [!IMPORTANT]
  67. > ArcRift is a powerful AI developer tool. Before installing the `.exe`, you must have [Node.js](https://nodejs.org/) and [Ollama](https://ollama.com/) installed on your computer to run the backend and local AI models. If you don't have these, use the *Developer (One-Command Setup)* below to automatically install them!
  68. 1. Head over to the [Releases](https://github.com/Eshaan-Nair/ArcRift/releases) page.
  69. 2. Download the latest `ArcRift_Installer.exe` (or your OS equivalent).
  70. 3. Double-click the installer to install ArcRift on your machine.
  71. 4. Launch ArcRift from your Start menu! The app will live entirely in your system tray and run seamlessly in the background.
  72. ### For Developers (Building from Source)
  73. If you want to modify the code, build the project yourself, or use the MCP Tools:
  74. **1. One-Command Setup (All Platforms)**
  75. ```bash
  76. npx arcrift-setup
  77. ```
  78. ```bash
  79. copy .env.example .env
  80. ```
  81. This clones the repo, checks dependencies, pulls Ollama models, installs packages, builds the backend, and sets up the env file.
  82. **2. Launching the Development Server**
  83. To launch the native desktop application in dev mode:
  84. ```bash
  85. npm run dev:desktop
  86. ```
  87. or
  88. ```bash
  89. cd dashboard
  90. npm run dev
  91. ```
  92. ```bash
  93. cd backend
  94. npm run dev
  95. ```
  96. This will start the backend seamlessly in the background and open the native ArcRift dashboard. When you close the window, it will minimize to your system tray. You can fully quit ArcRift from the tray menu.
  97. ### Web Extension Setup
  98. The extension requires the ArcRift backend to be running. If you have the **ArcRift Desktop App** running in your system tray, you are already good to go!
  99. **Step 1 — Install the Extension**
  100. **For Google Chrome / Edge / Brave:**
  101. 1. Download the Chrome `.zip` file from the [GitHub Releases](https://github.com/Eshaan-Nair/ArcRift/releases) page.
  102. 2. Extract the `.zip` file to a permanent folder on your computer.
  103. 3. Open `chrome://extensions`
  104. 4. Enable **Developer mode** (top-right toggle)
  105. 5. Click **Load unpacked** and select the folder you just extracted.
  106. 6. The ArcRift icon will appear in your toolbar!
  107. **For Mozilla Firefox:**
  108. 1. Download the officially signed `.xpi` file from the [GitHub Releases](https://github.com/Eshaan-Nair/ArcRift/releases) page.
  109. 2. Simply **drag and drop** the `.xpi` file directly into your open Firefox window.
  110. 3. Click **Add** when prompted. It will be installed permanently!
  111. **Step 2 — Use it**
  112. Navigate to Claude, ChatGPT, Gemini, DeepSeek, Grok, Copilot, or Mistral. Click the ArcRift popup, enter a project name, and click **Save Chat**. Auto-connect activates immediately.
  113. ---
  114. ### MCP Server Setup
  115. The MCP server runs as a separate process and communicates with AI coding tools over stdio. The backend does **not** need to be running as an HTTP server — the MCP server initializes its own storage connection.
  116. **Step 1 — Build the backend**
  117. ```bash
  118. cd backend
  119. npm install
  120. npm run build
  121. ```
  122. This produces `backend/dist/mcp/server.js`.
  123. **Step 2 — Generate your config (easiest)**
  124. ```bash
  125. cd backend
  126. npm run mcp:config
  127. ```
  128. This prints a pre-formatted JSON block with absolute paths resolved for your machine. Copy it directly into your tool's config file.
  129. **Step 3 — Add to your AI tool**
  130. **Claude Desktop** — `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/.claude/claude_desktop_config.json` (macOS):
  131. ```json
  132. {
  133. "mcpServers": {
  134. "arcrift": {
  135. "command": "node",
  136. "args": ["C:/path/to/ARCRIFT/backend/dist/mcp/server.js"]
  137. }
  138. }
  139. }
  140. ```
  141. **Claude Code** — run in your project directory:
  142. ```bash
  143. claude mcp add ArcRift node /path/to/ARCRIFT/backend/dist/mcp/server.js
  144. ```
  145. **Cursor** — create `.cursor/mcp.json` in your project root:
  146. ```json
  147. {
  148. "mcpServers": {
  149. "arcrift": {
  150. "command": "node",
  151. "args": ["/path/to/ARCRIFT/backend/dist/mcp/server.js"]
  152. }
  153. }
  154. }
  155. ```
  156. **Windsurf** — create `.windsurf/mcp.json` in your project root:
  157. ```json
  158. {
  159. "mcpServers": {
  160. "arcrift": {
  161. "command": "node",
  162. "args": ["/path/to/ARCRIFT/backend/dist/mcp/server.js"]
  163. }
  164. }
  165. }
  166. ```
  167. > Use forward slashes in all paths, even on Windows. Restart your AI tool after editing the config.
  168. **Step 4 — Set the storage mode**
  169. The MCP server reads `backend/.env`. Make sure it contains:
  170. ```
  171. ARCRIFT_STORAGE_MODE=sqlite
  172. OLLAMA_URL=http://localhost:11434
  173. ```
  174. Ollama must be running for the MCP server to generate embeddings and extract knowledge graph triples.
  175. ---
  176. ### Running Both Together
  177. When running the browser extension and MCP server together, they share the same `ArcRift.db` database. No extra configuration is needed.
  178. 1. Start the HTTP backend: `start.bat` or `./start.sh`
  179. 2. Load the extension in Chrome (it talks to `http://localhost:3001`)
  180. 3. Your AI coding tool starts the MCP server automatically when you open a project
  181. Memory saved via the extension is immediately available in `recall_context`, and memory stored via `store_memory` appears in the dashboard history. They are the same database.
  182. The HTTP backend and MCP server both use WAL mode on SQLite, which allows them to read and write concurrently without locking each other out.
  183. ---
  184. ## Usage Guide
  185. ### Using the Browser Extension
  186. **Saving a conversation:**
  187. 1. Have a conversation on any supported platform
  188. 2. Click the ArcRift icon in your browser toolbar
  189. 3. Enter a project name (e.g. `AuthService`, `MyApp-Backend`)
  190. 4. Click **Save Chat**
  191. ArcRift scrubs PII, chunks the text, embeds it locally with Ollama, and sends it to the backend. The UI confirms success in under 5 seconds. Background indexing (sentence-level embeddings, knowledge graph extraction) continues asynchronously.
  192. **Auto-connect:**
  193. Once a session is saved and activated, ArcRift intercepts every prompt you type on that platform. Before the request is sent, it queries the backend for relevant context and prepends the top results. You do not need to do anything — just type normally.
  194. To pause: click the ArcRift popup and hit **Pause**. The badge dims. Click again to resume.
  195. **New chat detection:**
  196. When you click "New Chat" on ChatGPT, Claude.ai, or Gemini, ArcRift detects the URL or DOM change and resets the active session. The next Save will start a fresh project, and context from the previous session will not bleed in.
  197. **Classic inject:**
  198. For a one-time context push without enabling auto-connect, click **Inject Context** in the popup. ArcRift pastes the knowledge graph summary directly into the chat input field. You review it and send manually.
  199. ---
  200. ### Using the MCP Tools
  201. Once connected, your coding agent has access to seven ArcRift tools. A typical session looks like this:
  202. **At session start — recall project memory:**
  203. ```
  204. Use recall_context with prompt: "implementing JWT refresh token rotation"
  205. and project: "AuthService"
  206. ```
  207. **After completing work — save decisions:**
  208. ```
  209. Use store_memory with content: "We implemented refresh token rotation using
  210. Redis for token invalidation. The key insight was using a sliding expiry window
  211. of 15 minutes for access tokens and 7 days for refresh tokens." and project: "AuthService"
  212. ```
  213. **Finding something from a different project:**
  214. ```
  215. Use search_memory with query: "rate limiting strategy"
  216. ```
  217. **Getting an overview before starting:**
  218. ```
  219. Use get_project_summary for project: "AuthService"
  220. ```
  221. **Auto-detecting the current project:**
  222. ```
  223. Use identify_active_project with path: "/Users/me/code/auth-service"
  224. ```
  225. **Correcting outdated information:**
  226. ```
  227. Use prune_memory with prompt: "Redis rate limiting" and project: "AuthService"
  228. ```
  229. ---
  230. ### Dashboard
  231. Open `http://localhost:3001` while the backend is running.
  232. | Tab | What you see |
  233. |:---|:---|
  234. | **Graph** | D3.js force-directed knowledge graph. Nodes are entities, edges are relations. Degree-scaled sizing — high-connectivity nodes appear larger. Hover for details, scroll to zoom, drag to reposition. |
  235. | **History** | All extracted triples (subject / relation / object) with timestamps. Filterable by project and relation type. |
  236. | **Chat** | The full saved conversation rendered as color-coded chat bubbles, with platform attribution. |
  237. | **Job Queue** | Live view of background indexing jobs — pending, processing, completed, dead-lettered. |
  238. ## System Requirements
  239. | Mode | Min RAM | Disk | Docker | What runs |
  240. |:---|:---|:---|:---|:---|
  241. | **SQLite (Recommended)** | 2 GB | 3 GB | Not required | All features — single `.db` file + Ollama |
  242. | **Full Docker** | 8 GB | 15 GB | Required | Neo4j + MongoDB + ChromaDB + Ollama |
  243. | **Lite Docker** | 4 GB | 10 GB | Required | MongoDB + ChromaDB (no knowledge graph) |
  244. SQLite mode is the recommended default. The installer detects Docker automatically and sets SQLite mode if Docker is not available.
  245. ### Prerequisites
  246. | Requirement | Version | Notes |
  247. |:---|:---|:---|
  248. | Node.js | 20 LTS+ | [nodejs.org](https://nodejs.org) |
  249. | Ollama | Latest | [ollama.com](https://ollama.com) — required for local embeddings and extraction |
  250. | Docker Desktop | 24.0+ | [docker.com](https://docker.com) — only needed for Docker mode |
  251. | Groq API Key | — | [console.groq.com](https://console.groq.com) — free, used as fallback if Ollama is slow |
  252. ---
  253. ## Key Features
  254. ### Core Retrieval Engine
  255. | Feature | Detail |
  256. |:---|:---|
  257. | **Three-Layer Hybrid Search** | Sentence vectors, chunk vectors, and FTS5 keyword search run in parallel. Results are fused and ranked by a combined score. |
  258. | **Surgical Sentence Trimming** | Chunks are split into individual sentences at index time. On retrieval, only the sentences that directly match the query are returned — not the entire surrounding paragraph. Reduces prompt noise by up to 95%. |
  259. | **HyDE (Hypothetical Document Embedding)** | Before querying the vector store, ArcRift generates a hypothetical answer to your query and uses that embedding alongside the raw query. This dramatically improves recall for rephrased or indirect questions. |
  260. | **Small-to-Big Retrieval** | High-precision sentence match triggers fetching the parent chunk for broader context. Precision of a sentence search, context of a full paragraph. |
  261. | **Knowledge Graph Layer** | Every saved conversation is processed to extract subject-relation-object triples (22 entity types, 20+ relation types). Graph facts are fused with vector results on every recall. |
  262. | **Background Indexing** | Sentence-level embedding is offloaded to a background job queue so Save is instant. The deep index is built asynchronously without blocking the UI. |
  263. ### Extension Quality-of-Life
  264. | Feature | Detail |
  265. |:---|:---|
  266. | **Auto-Connect** | Once a session is active, ArcRift re-attaches automatically on every page load. No clicking required — just type. |
  267. | **SPA Navigation Awareness** | Detects "New Chat" clicks in single-page apps (ChatGPT, Claude, Gemini) without a full page reload. Automatically resets the active session so context does not bleed between conversations. |
  268. | **Pause / Resume** | One click in the popup pauses auto-injection. Click again to resume. State persists across tabs. |
  269. | **Classic Inject** | One-time manual inject button for priming a cold start without enabling auto-connect. |
  270. | **FNV-1a Deduplication** | Identical conversation segments are fingerprinted and skipped — re-saving a chat never creates duplicate embeddings. |
  271. | **Multi-Strategy DOM Resolver** | Each platform has five ordered selector strategies. If one breaks after a UI update, the next activates automatically. |
  272. | **Restricted URL Guard** | Injection is blocked on `chrome://`, `about:`, and extension pages. Prevents crashes on non-chat pages. |
  273. ### MCP Tool Quality-of-Life
  274. | Tool | What it does |
  275. |:---|:---|
  276. | `recall_context` | Retrieves the top-N most relevant memory chunks for a prompt, scoped to a project. Includes knowledge graph facts. |
  277. | `store_memory` | Saves text or a transcript to ArcRift Memory. Auto-creates the project if it does not exist. Triggers full background indexing. |
  278. | `search_memory` | Cross-project global search. Useful for finding decisions made in a different project that apply to the current one. |
  279. | `list_projects` | Lists all saved projects with metadata — chunk count, triple count, last updated. |
  280. | `get_project_summary` | Returns a structured knowledge graph summary for a project as readable markdown. |
  281. | `identify_active_project` | Matches a folder path against saved project names. Lets the AI agent auto-detect which project it is working on from the CWD. |
  282. | `prune_memory` | Surgically removes facts or chunks matching a description. Corrects outdated information without wiping an entire project. |
  283. ### Infrastructure
  284. | Feature | Detail |
  285. |:---|:---|
  286. | **Zero-Docker Mode** | `ARCRIFT_STORAGE_MODE=sqlite` replaces all Docker services with a single `ArcRift.db` file. Full feature parity — vector search, knowledge graph, job queue, everything. |
  287. | **WAL Concurrency** | SQLite runs in Write-Ahead Logging mode, allowing simultaneous reads from the dashboard, extension, and MCP server without lock contention. |
  288. | **Dead Letter Queue** | Background jobs that fail are retried up to 5 times with exponential backoff. Failed jobs move to a dead letter queue visible in the dashboard — nothing is silently lost. |
  289. | **Ghost Job Cleanup** | On startup, any jobs stuck in PROCESSING state from a previous crashed run are automatically reset to PENDING. |
  290. | **Rate Limiting** | Save endpoint is rate-limited independently from read endpoints. Prevents accidental flooding from rapid saves. |
  291. | **Helmet Security Headers** | All responses include `Content-Security-Policy`, `X-Frame-Options`, `X-Content-Type-Options`, and related headers. |
  292. ---
  293. ## Architecture
  294. ```
  295. ARCRIFT/
  296. ├── backend/
  297. │ ├── src/
  298. │ │ ├── mcp/ MCP server and seven tool implementations
  299. │ │ ├── routes/ REST API (chat, rag, session, jobs)
  300. │ │ ├── services/ Storage bridge, SQLite engine, vector store,
  301. │ │ │ graph store, embeddings, job queue, extractor
  302. │ │ ├── middleware/ Rate limiting, sanitization, CORS
  303. │ │ └── utils/ Logger, privacy scrubber
  304. │ └── scripts/ Benchmarking, stress testing, maintenance tools
  305. ├── dashboard/ React 19 + D3.js + Vite — built to dashboard/dist/
  306. ├── extension/
  307. │ ├── src/
  308. │ │ ├── platform/ Multi-strategy DOM resolver
  309. │ │ ├── platforms/ claude, chatgpt, gemini, deepseek, grok, copilot, mistral
  310. │ │ ├── content.ts DOM scraping, prompt interception, auto-connect
  311. │ │ └── background.ts Service worker, backend proxy
  312. │ └── popup/ Popup UI and controls
  313. ├── reports/ Benchmark and audit outputs
  314. ├── .env.example Configuration template
  315. ├── docker-compose.yml Full Docker profile
  316. ├── install.bat / .sh First-time setup
  317. └── start.bat / .sh Daily launcher
  318. ```
  319. ### Ports
  320. | Service | Port | Notes |
  321. |:---|:---|:---|
  322. | Backend API + Dashboard | 3001 | Single process — API and static files |
  323. | MCP Server | stdio | Spawned by your AI tool on demand |
  324. | Ollama | 11434 | Local LLM and embeddings |
  325. | Neo4j | 7474 / 7687 | Docker full mode only |
  326. | MongoDB | 27017 | Docker mode only |
  327. | ChromaDB | 8000 | Docker mode only |
  328. ### Tech Stack
  329. | Layer | Technology |
  330. |:---|:---|
  331. | Extension | TypeScript, Chrome MV3, esbuild |
  332. | Backend | Node.js, Express 5, TypeScript, Pino |
  333. | Vector Store | SQLite-vec (vec0 virtual tables, 768-dim float32) |
  334. | Full-Text Search | SQLite FTS5 with Porter stemmer |
  335. | Knowledge Graph | SQLite facts table (or Neo4j in Docker mode) |
  336. | Embeddings | Ollama `nomic-embed-text` (768-dim, CPU-optimized) |
  337. | LLM | Ollama `llama3.1:8b` primary — Groq fallback |
  338. | MCP | `@modelcontextprotocol/sdk` v1.29+ (stdio transport) |
  339. | Dashboard | React 19, Vite 7, D3.js v7 |
  340. | Static Serving | sirv (served from same process as the API) |
  341. | Security | Helmet, express-rate-limit |
  342. ---
  343. ## Quality-of-Life Details
  344. These are the smaller decisions that make the system faster and more reliable in practice.
  345. **Instant save, deep index later.** When you click Save, only the chunk-level embeddings are computed synchronously (1–2 embeddings). Sentence-level embeddings (20–40 embeddings per conversation) are offloaded to a background job. The UI confirms success immediately; the deep index catches up within seconds.
  346. **Delete-then-insert for vector updates.** SQLite virtual tables do not support `UPDATE` on vector columns. ArcRift uses a delete-then-insert pattern to avoid `UNIQUE constraint` errors when re-saving a conversation.
  347. **Prefix keyword matching.** FTS5 queries use wildcard suffixes (`encrypt*` matches `encryption`, `encrypted`, `encryptor`). This significantly improves recall for technical terms where the exact suffix varies.
  348. **Threshold set at 0.30, not 0.45.** Surgical trimming allows a lower similarity threshold. Even if a chunk is only loosely related, if the matching sentences are precise, the noise penalty is near zero.
  349. **History-aware fallback.** If a query is detected as a history-seeking question ("what did we talk about", "what was decided"), the trimmer falls back to the first three sentences of the chunk rather than returning nothing.
  350. **5-character minimum sentence filter.** The sentence splitter ignores fragments shorter than 5 characters. This prevents code snippets and punctuation artifacts from polluting the sentence index.
  351. **WAL mode on all writes.** SQLite is opened in WAL mode on startup. The MCP server, HTTP backend, and dashboard can all read and write concurrently without database lock errors.
  352. **Ghost job recovery.** On startup, any jobs stuck in `PROCESSING` from a previous crash are reset to `PENDING` automatically. No manual intervention needed after an unclean shutdown.
  353. **CORS locked to localhost.** The backend only accepts requests from `localhost` origins. External requests are rejected before they reach any route handler.
  354. ---
  355. ## How It Works
  356. ```
  357. SAVE
  358. Browser scrapes conversation → FNV-1a dedup check
  359. → PII scrub (API keys, JWTs, emails, IPs → [REDACTED])
  360. → POST to backend
  361. STORAGE (two parallel tracks)
  362. Vector Track Graph Track
  363. Sliding window chunker Text sent to Ollama llama3.1:8b
  364. 300 words, 80-word overlap (Groq as fallback)
  365. Embeds with nomic-embed-text Extracts subject-relation-object triples
  366. Stores in SQLite vec0 Stores in SQLite facts table
  367. Background: sentence-level Background: stores after chunk embedding
  368. embedding job queued
  369. RECALL (on every prompt or tool call)
  370. Query → HyDE (generate hypothetical answer → embed both)
  371. → Sentence vector search (top 100, filter by session)
  372. → Chunk vector search (top 20, filter by session)
  373. → FTS5 keyword search (prefix match, filter by session)
  374. → Fuse results, score, deduplicate
  375. → Surgical trim (keep only matching sentences from each chunk)
  376. → sanitizeChunks() (scan for injection patterns → redact)
  377. → wrapInContextBlock() (lean text header)
  378. → Prepend to prompt
  379. ```
  380. ---
  381. ## How the Two Modes Work
  382. ArcRift has two complementary modes that share the same memory store. You can use one, the other, or both at the same time.
  383. ### Mode 1 — Browser Extension (Web)
  384. The extension lives inside Chrome and works on any AI chat website. When you save a conversation, it scrapes the page, scrubs PII, chunks and embeds the text locally, and sends it to the ArcRift backend. On every subsequent prompt you type, the extension intercepts the input, queries the backend for relevant context, and prepends it to your message automatically — before the request hits the AI.
  385. Best for: Claude, ChatGPT, Gemini, DeepSeek, Grok, Microsoft Copilot, and Mistral web interfaces.
  386. ### Mode 2 — MCP Server (Coding Tools)
  387. The MCP server exposes ArcRift as a set of tools that coding agents can call directly. Instead of intercepting DOM events, the AI tool calls `recall_context` at the start of a session to pull in relevant memory, and `store_memory` after completing work to save decisions and context for future sessions.
  388. Best for: Claude Code, Cursor, Windsurf — anywhere you write code with an AI coding agent.
  389. ### Shared Memory
  390. Both modes write to and read from the same backend database. A conversation you save via the browser extension is immediately available to `recall_context` in your coding tool, and vice versa. They are two interfaces into one unified knowledge base.
  391. ---
  392. ## Performance Benchmarks
  393. Every release is stress-tested across four independent audits. All results are reproducible using the scripts in `backend/scripts/`.
  394. ### Web Context Engine (Browser Extension)
  395. **Scale:** 1,000 chunks (~300,000 words) | **Needles:** 20 facts | **Queries:** 60 phrasings
  396. | Metric | Result | What it means |
  397. |:---|:---|:---|
  398. | **Recall @ 1** | **90.0%** | Correct fact was the top result in 54 of 60 searches |
  399. | **Mean Reciprocal Rank** | **0.806** | Correct answer appears at position 1.24 on average (1.0 is perfect) |
  400. | **Context Compression** | **95.0%** | Payload reduced from 55,350 chars to 2,784 chars before injection |
  401. | **Mean Relevance Score** | **0.464** | Average semantic similarity of retrieved results (0–1 scale) |
  402. Engine contribution across 54 successful recalls:
  403. | Engine | Hits | Role |
  404. |:---|:---|:---|
  405. | Sentence Vector | 50 | High-precision match against individual sentences |
  406. | Chunk Vector | 47 | Thematic match against full 150-word context windows |
  407. | FTS5 Keyword | 43 | Exact literal matching, boosts low-similarity vector results |
  408. The 6 misses were all on degenerate "Context on X?" queries with no semantic content. All natural-language and rephrased queries passed.
  409. Full report: [reports/benchmark_web.md](reports/benchmark_web.md)
  410. ---
  411. ### MCP Context Engine (Coding Tools)
  412. **Scale:** 10 facts across real project memory | **Queries:** 30 (3 phrasings each) | **TopN:** 6
  413. | Metric | Result | Target | |
  414. |:---|:---|:---|:---|
  415. | **Total Recall** | **90%** | >90% | PASS |
  416. | **Context Compression** | **81.3%** | >75% | PASS |
  417. | **Noise Redacted** | **131,700 chars** | — | vs. returning 6 full chunks raw |
  418. Engine contribution across 27 successful recalls:
  419. | Engine | Hits | Contribution |
  420. |:---|:---|:---|
  421. | Sentence Vector | 26 | 100% of recalls |
  422. | FTS Keyword | 24 | 92.3% of recalls |
  423. | Chunk Vector | 9 | 34.6% of recalls |
  424. The 3 misses were all on highly rephrased semantic queries with no shared keywords. Standard and lowercase phrasings passed in every case.
  425. Full report: [reports/benchmark_mcp.md](reports/benchmark_mcp.md)
  426. ---
  427. ### MCP Project Isolation Audit
  428. **Scale:** 10 simultaneous projects | **Checks:** Store + own-recall + cross-leak per project
  429. | Metric | Result | Status |
  430. |:---|:---|:---|
  431. | **Isolation Integrity** | **100%** | ELITE — zero cross-project leakage |
  432. | **Concurrent Access** | **Pass** | All projects readable under simultaneous load |
  433. | **Leak Detection** | **Negative** | No data from any project visible in another |
  434. Each project's vector space and knowledge graph is strictly siloed via `sessionId` constraints. Aggressive cleanup logic purges both IDs and Names between runs to prevent identity drift.
  435. Full report: [reports/mcp_stress_test.md](reports/mcp_stress_test.md)
  436. ---
  437. ### Knowledge Graph Stress Audit
  438. **Scale:** 1,200+ nodes, 1,087 triples in a single session
  439. | Metric | Result | Status |
  440. |:---|:---|:---|
  441. | **Total Triples Stored** | **1,087** | PASS |
  442. | **Ingestion Throughput** | **4,056 triples/sec** | OPTIMIZED |
  443. | **Generation Time** | **0.3 seconds** | ELITE |
  444. | **Dashboard Load** | **< 1.5 seconds** | Physics-simulated D3.js render |
  445. | **Storage Cost** | **~0.2 MB** | SQLite increase for entire stress session |
  446. Graph structure: 5 major hubs (40+ edges each), 15 intermediate clusters, 400 mesh entities, 100 isolated standalone facts.
  447. Full report: [reports/graph_stress_test.md](reports/graph_stress_test.md)
  448. ---
  449. ## Privacy and Security
  450. ArcRift was designed with a local-first philosophy from the ground up. Your conversations never leave your machine unless you explicitly configure a cloud LLM.
  451. | Control | Detail |
  452. |:---|:---|
  453. | **Local Storage** | All data lives in `ArcRift.db` on your machine or in local Docker volumes. Nothing syncs to any external service. |
  454. | **Local Embeddings** | `nomic-embed-text` runs entirely via Ollama — zero API calls for embeddings. |
  455. | **Local Extraction** | `llama3.1:8b` runs via Ollama for knowledge graph extraction. Groq is only used as a fallback and only if you provide a key. |
  456. | **PII Scrubbing** | API keys, JWTs, connection strings, email addresses, and internal IPs are redacted to `[REDACTED]` in the browser before any data is sent to the backend. |
  457. | **Injection Defence** | Retrieved chunks are scanned for 10 known prompt injection patterns before being injected into any prompt. Matching content is replaced with `[Content redacted]`. |
  458. | **CORS Locked** | The backend rejects requests from any origin other than `localhost`. |
  459. | **Security Headers** | Helmet adds `CSP`, `X-Frame-Options`, `X-Content-Type-Options`, and other headers to every response. |
  460. | **No Shared Secret** | The pre-v1.4.7 shared secret requirement has been removed. The extension communicates directly with the local backend. |
  461. See [SECURITY.md](SECURITY.md) for the full threat model and vulnerability reporting policy.
  462. ---
  463. ## Comparison with Alternatives
  464. While tools like Mem0, Zep, and Letta focus heavily on providing memory APIs for agent developers, **ArcRift is built directly for end-users and human-in-the-loop workflows.**
  465. | Feature | ArcRift | Mem0 | Zep | Letta (MemGPT) | LangGraph |
  466. |:---|:---|:---|:---|:---|:---|
  467. | **Primary Audience** | **End-users & Devs** | Agent Devs | Agent Devs | Agent Devs | Agent Devs |
  468. | **Cross-Platform Chat UX** | **Yes (Injects directly into ChatGPT, Claude, etc)**| Bring your own UI | Bring your own UI | Bring your own UI | Bring your own UI |
  469. | **Visual Knowledge Graph** | **Yes (D3 Dashboard)** | API Only | API Only | No | Optional / Custom |
  470. | **Context Retrieval Precision**| **Surgical Sentence Trimming (95% noise reduction)** | Full Chunk | Full Chunk | Full Chunk | Varies by implementation |
  471. | **Setup Complexity** | **1 command (`npx`)** | Requires DB / API | Requires DB / Docker | Docker / Python env | Code-heavy (Framework) |
  472. | **Storage Backend** | **SQLite (Zero config)** | PostgreSQL / Qdrant | PostgreSQL / Redis | PostgreSQL / Chroma | Any (BYO Database) |
  473. | **Local vs Cloud** | **100% Local (Ollama)** | Cloud-first (Local avail) | Both | Both | Both |
  474. | **Native IDE Integration**| **Yes (via MCP)**| API Only | API Only | API Only | API Only |
  475. | **MCP Support** | **Yes** | Yes | Yes | Yes | Yes |
  476. | **License** | MIT | Apache 2.0 | Apache 2.0 | Apache 2.0 | MIT |
  477. ---
  478. ## What's New in v1.6.3
  479. This release brings full cross-browser support to ArcRift and patches a critical context injection bug.
  480. - **Mozilla Firefox Support**: ArcRift is now fully compatible with Firefox! The extension build pipeline generates independent Chrome and Firefox packages, and we have fully automated the Mozilla Add-ons signing pipeline so signed `.xpi` extensions are attached to every release.
  481. - **RAG Hallucination Fix**: We caught a bug where out-of-context chats were injecting irrelevant project memory because the vector DB returned the top closest matches no matter how semantically distant they actually were. The retrieval pipeline now enforces a strict 50% relevance threshold.
  482. *(Note: If you were testing `v1.6.1` locally, all core desktop app updates remain the same in this release).*
  483. See [CHANGELOG.md](CHANGELOG.md) for the full history.
  484. ---
  485. ## Documentation
  486. | File | Description |
  487. |:---|:---|
  488. | [ARCHITECTURE.md](ARCHITECTURE.md) | Data flow, storage schema, environment variables |
  489. | [RAG_PIPELINE.md](RAG_PIPELINE.md) | Retrieval pipeline, scoring, threshold tuning |
  490. | [MCP_SETUP.md](MCP_SETUP.md) | MCP setup guide for all supported tools |
  491. | [PLATFORM_SELECTORS.md](PLATFORM_SELECTORS.md) | DOM resolver system, adding new platforms |
  492. | [SECURITY.md](SECURITY.md) | Threat model, vulnerability reporting |
  493. | [SELF_HOSTING.md](SELF_HOSTING.md) | Ports, passwords, backups, reverse proxy |
  494. | [CONTRIBUTING.md](CONTRIBUTING.md) | Fork workflow, commit format, adding platforms |
  495. | [CHANGELOG.md](CHANGELOG.md) | Full version history |
  496. | [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | Common issues and fixes |
  497. ---
  498. ## Contributing
  499. Bug fixes, new platform support, UI improvements, and test coverage are all welcome.
  500. [Contributing Guide](CONTRIBUTING.md) · [Code of Conduct](CODE_OF_CONDUCT.md)
  501. Good first issues: [`good first issue`](https://github.com/Eshaan-Nair/ARCRIFT/issues?q=is%3Aissue+label%3A%22good+first+issue%22)
  502. ---
  503. ## License
  504. MIT — see [LICENSE](LICENSE).
  505. ---
  506. <div align="center">
  507. <br/>
  508. **Stop re-explaining yourself. Give your AI the memory it should have had from day one.**
  509. *Built by [Eshaan Nair](https://github.com/Eshaan-Nair)*
  510. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/eshaan-nair-arcrift-badge.png)](https://mseep.ai/app/eshaan-nair-arcrift)
  511. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.