<p align="center">
  <img src="https://img.shields.io/github/actions/workflow/status/NitishKashyapR/unified-ai-memory/ci.yml?branch=main&label=CI&logo=github&style=for-the-badge" alt="CI status">
  <img src="https://img.shields.io/github/stars/NitishKashyapR/unified-ai-memory?style=for-the-badge" alt="GitHub stars">
  <img src="https://img.shields.io/github/downloads/NitishKashyapR/unified-ai-memory/total?style=for-the-badge" alt="Downloads">
  <img src="https://img.shields.io/github/v/release/NitishKashyapR/unified-ai-memory?style=for-the-badge" alt="Latest release">
  <img src="https://img.shields.io/badge/license-MIT-9b9b9b?style=for-the-badge" alt="MIT License">
</p>

<h1 align="center">🧠 AIBrain — offline-first AI memory &amp; MCP server for coding agents</h1>

<p align="center">
  One Markdown memory on your machine, wired into every agent you run.<br>
  <b>Shared via MCP · ONNX semantic search · RAG chat · Human-brain lifecycle · 100% local</b>
</p>

<p align="center">
  <a href="#-why-aibrain">Why AIBrain?</a> ·
  <a href="#-features">Features</a> ·
  <a href="#-install">Install</a> ·
  <a href="#-quick-start">Quick start</a> ·
  <a href="#-mcp-tools">MCP Tools</a> ·
  <a href="#-faq">FAQ</a> ·
  <a href="#-development">Development</a> ·
  <a href="#-license">License</a>
</p>

---

**AIBrain** is a local-first, privacy-respecting **AI memory manager** for
developers who run coding agents. Every agent you use — opencode, Claude Code,
Codex, Cursor, Zed, and 15+ more — reads and writes the **same Markdown memory
folder** through a local **MCP server**, with **fully offline semantic search**
(vendored ONNX `all-MiniLM-L6-v2` embeddings), **RAG chat** with numbered
citations, and a human-brain-like memory lifecycle: noise is filtered at write
time, durable facts are promoted to the library, old entries are archived.
**Your memory never leaves your machine** — no cloud, no telemetry.

---

## ✨ Why AIBrain?

- **One brain, every agent** — a shared memory your whole agent fleet reads and
  writes through the Model Context Protocol (MCP). No more per-tool memory
  silos or re-explaining your project to each new agent.
- **Truly offline** — embeddings are computed on your machine with a vendored
  ONNX model; no API keys, no data exfiltration, no remote model calls.
- **Semantic, not just keyword** — find notes by meaning with local vector
  search, or ask questions in plain language and get answers grounded in your
  memory with numbered citations.
- **Memory that behaves like a brain** — noise-gated writing, promote/demote
  curation, mutation journal with one-click undo, and retention with a
  hard 7-day safety floor. Nothing is ever silently deleted.
- **Free & open source** — MIT licensed, Rust + Tauri 2 + React, no paid tiers.

## ✨ Features

### 🔎 Semantic vector search

- **Fully offline embeddings** — the ONNX `all-MiniLM-L6-v2` model (384-dim) and
  its WASM runtime are vendored in-app; remote model fetching is disabled.
- **SQLite vector store** (`{brain}/.aibrain/vec.db`) with brute-force cosine
  search — plenty for a personal brain of hundreds of entries.
- **Content-hash auto re-indexing** — each entry is FNV-1a hashed; only changed
  entries are re-embedded, so formatting-only edits never trigger re-indexing.
- Model-change safety: vectors from a different embedding model never match.

### 💬 Ask your brain

- RAG chat over your memory: the top vector hits are pulled as context, the
  model answers **only from those notes**, with numbered **【n】 citations** and
  source chips (title, date, score).
- Backed by **OpenRouter** (bring a key) or any local OpenAI-compatible provider
  — **LM Studio, Ollama or BionicGPT**, auto-detected and applied in one click.
- One-shot completions (no streaming yet).

### 🧠 Human-brain memory lifecycle

- **Write-time noise gate** — greetings, acks and bare pasted commands are
  classified as chatter and diverted to `inbox/_buffer.md` instead of the
  dated session log (off by never losing substance — the classifier errs
  toward keeping).
- **Mutation journal + one-click undo** — every append, promote, demote and
  archive move is journaled and reversible.
- **Promote / demote** — inbox entries are promoted into `library/concepts/`
  as curated notes (slug per topic, dated sections); demote removes them again.
- **Retention** — inbox files older than N days are archived into
  `archive/YYYY-MM-DD/`, with a hard **7-day safety floor**: nothing younger
  than that is ever touched, nothing is ever deleted.
- **Background librarian** — periodically consolidates the buffer into today's
  log (rule-based noise filter + dedup), optionally distilling it through your
  configured local LLM so only durable facts survive ("human-brain mode").

### 🔌 Agent MCP server

A small stdio server (`mcp-server`, bundled as a sibling binary) exposes the
memory to any MCP-capable client — **12 tools**, see below. The dashboard scans
your machine, lists **only installed agents**, and wires each one with a real
MCP handshake (no auto-connect). Connections point at a **stable copy** of the
server in the app data dir, so they survive reinstalls — and the scan
self-heals stale entries. Works with opencode, Claude Code, Claude Desktop,
Codex, Cursor, VS Code, Zed, Windsurf, Cline, Continue, Gemini CLI, Antigravity,
Goose, Aider, Qwen Code, Kimi CLI, Crush, Amp, OpenHands and Copilot CLI — or
any config file via universal connect.

### 🛰️ Synapse Observatory UI

- **14 themes** (Synapse, Midnight, Aurora, Dracula, Gruvbox, Nord, Forest,
  Hacker, Terminal, Paper Dark, Graphite, Solarized Light, One Light, Paper),
  dark and light, with WCAG-checked accent ink.
- **Offline fonts** — IBM Plex Sans + JetBrains Mono vendored in-app; nothing
  is fetched from the web.
- Pages: **Dashboard** (agent connections), **Memory** (searchable, attributed
  timeline), **Ask** (RAG chat), **Settings** (providers, librarian, themes) and
  **Onboarding** (pick or create your memory folder).

### 🔐 Local-first privacy

- **No telemetry, no cloud.** The only outbound traffic is the optional
  update check and an optional OpenRouter key you add for chat.
- Embeddings never leave the machine: in-app vectors are computed locally;
  agent-side `recall` only ever talks to a **localhost** endpoint you
  configured (anything else falls back to keyword search).
- The `audit` MCP tool reports exactly what network calls AIBrain can make.
- CSP locks the webview to local assets and the update endpoint.
- **Complete removal**: the uninstaller offers a
  **“Remove everything from this system”** tick box that strips every agent
  wire, injected instruction block, backup file and app data — or use
  Settings → *Remove everything & uninstall* in-app. A custom memory folder
  you picked yourself is never deleted by the uninstaller.

## 📥 Install

Grab **v0.3.0** from the
[**Releases**](https://github.com/NitishKashyapR/unified-ai-memory/releases)
page:

| Platform | Installers |
| :--- | :--- |
| **Windows** | `.exe` (NSIS installer) + `.msi` |
| **Linux** | `.deb` + `.AppImage` |
| **macOS** | `.dmg` + `.app` (unsigned — right-click → **Open** the first time) |

Auto-update is built in: the app checks the Releases page (`latest.json`) and
keeps itself current; artifacts are signed and verified against a key kept
only on the maintainer's machine.

## 🚀 Quick start

1. **Install** the app for your platform (above).
2. **Pick or create a memory folder** — a plain folder of Markdown. The brain
   layout (`library/`, `inbox/`, `index.md`) is created for you if missing;
   empty folders work.
3. **Connect your agents** — the Dashboard lists what's installed. Click
   **Connect** and the agent's config gets one standard MCP entry pointing at
   the brain. Claude Code and Cursor agents can then use the MCP tools
   directly in their sessions.
4. **Use Ask** — open the Ask page, type a question, get an answer grounded in
   your memory with 【n】 citations. Optionally add an OpenRouter key or point
   at a local provider in Settings first.
5. Agents append durable facts via `append_log`; check the Memory page to see
   everything recorded, attributed by agent and project.

## 🔌 MCP Tools

| Tool | Purpose |
| :--- | :--- |
| `read_note` | Read a memory note by path relative to the brain root |
| `list_notes` | List every memory note and session log |
| `append_log` | Append a dated, durable fact to today's session log (noise-gated) |
| `memory_summary` | Return the brain index — "what does this brain know" |
| `search_library` | Keyword search of notes + logs; up to 20 matches |
| `recall` | Semantic recall — vector search via a localhost embedding endpoint, keyword fallback otherwise |
| `recent_facts` | The last N memory entries, newest first |
| `open_threads` | Heuristic thread finder over the last ~14 days (pending/blocked/todo…) |
| `audit` | Prove exactly what network calls AIBrain can make (offline guarantee) |
| `session_start` / `session_end` | Track sessions and log their summaries |
| `propose_memory` | Propose a durable fact for human-reviewed curation |

## 🛠 Development

Prerequisites: **Node 20**, **Rust stable**, and the platform toolchain the
CI uses — on Ubuntu 22.04: `libwebkit2gtk-4.1-dev libappindicator3-dev
librsvg2-dev patchelf libgtk-3-dev`; Windows needs the MSVC toolchain; macOS
needs Xcode command line tools.

> PowerShell blocks the `npm.ps1` shim — on Windows always invoke `npm.cmd`.

```powershell
# app/
npm.cmd install
npm.cmd run build          # tsc + vite build (+ WASM trim)
npm.cmd run tauri dev      # run with hot reload

# app/src-tauri/
cargo test                 # workspace tests (core, mcp-server)
cargo build -p aibrain-mcp-server --release   # agent server binary

# app/ — embedding pipeline smoke test (model, dims, similarity)
node scripts/embed-smoke.mjs
```

Workspace layout:

```
app/                        React 19 + Vite + TypeScript frontend
app/src-tauri/              Tauri 2 shell + Tauri commands
app/src-tauri/crates/core/  aibrain-core — vectors, lifecycle, librarian,
                            chat, locals, settings, journal, connectors
app/src-tauri/crates/mcp-server/   the stdio MCP server binary
app/public/models|wasm|fonts|       vendored assets — never fetched at runtime
```

CI (`.github/workflows/ci.yml`) runs on every push/PR: frontend build + Rust
tests on Ubuntu 22.04 and Windows. Releases (`.github/workflows/release.yml`)
build all three OSes on `v*` tags, run tests, and draft a signed release with
installers + updater artifacts.

## 🗺 Roadmap

- Streaming chat (SSE) with tool-call visibility
- Knowledge-graph view of the memory
- Memory-health lint (orphans, broken wikilinks, duplicate facts)
- Lifecycle controls in the UI (undo / promote / retention), frontend tests

## ❓ FAQ

**Is my memory private?**
Yes. AIBrain is local-first: notes, embeddings and searches never leave your
machine. The only optional outbound traffic is the auto-update check and an
OpenRouter key you add yourself for the RAG chat. Run `audit` (MCP tool) to see
exactly what network calls AIBrain can make.

**Does it need a GPU or an API key?**
No. Semantic search runs fully offline on CPU with a vendored ONNX model. For
the Ask (RAG chat) page you can bring an OpenRouter key or point at any local
OpenAI-compatible server (LM Studio, Ollama, BionicGPT) — or skip chat entirely
and use AIBrain purely as an agent memory store.

**Which AI agents does it work with?**
opencode, Claude Code, Claude Desktop, Codex, Cursor, VS Code, Zed, Windsurf,
Cline, Continue, Gemini CLI, Goose, Aider, Qwen Code, Kimi CLI, OpenHands,
Copilot CLI and more — anything that speaks MCP, plus universal config connect
for the rest.

**How is this different from AGENTS.md / CLAUDE.md?**
Those are per-project static rule files. AIBrain is a living, searchable,
cross-project memory: session logs, curated concepts and threads that every
agent can recall semantically — not just the one that wrote the file.

**Is anything ever deleted?**
No. Retention archives old inbox entries to dated folders with a hard 7-day
safety floor, and every mutation is journaled so it can be undone.

## 📄 License

MIT — see [LICENSE](LICENSE).

---

<sub>Built with Tauri 2 · Rust core · React + TypeScript · works with opencode,
Claude Code, Codex, Cursor, VS Code, Zed & friends</sub>