# Vidurai: Local-First AI Memory Layer

[![PyPI](https://img.shields.io/pypi/v/vidurai)](https://pypi.org/project/vidurai/)
[![License](https://img.shields.io/pypi/l/vidurai)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

**Vidurai** (v2.2.0) is a local background service that indexes your development context. It bridges your local codebase with AI tools (like Claude, Cursor, and VS Code) without uploading your source code to third-party vector clouds.

It runs locally, stores data locally (`~/.vidurai`), and serves context via the **Model Context Protocol (MCP)** and **IPC**.

> *विस्मृति भी विद्या है (Forgetting too is knowledge)* — The system intelligently compresses and forgets low-value context while preserving critical insights.

---

## Installation

### Step 1: Install the Brain
We recommend `pipx` to isolate dependencies.
```bash
pipx install vidurai
# OR
pip install vidurai
```

### Step 2: Start the Guardian
```bash
vidurai start
# Output: Vidurai Guardian started (PID: 12345)
```

### Verify Installation
```bash
vidurai --version
vidurai status
```

---

## Integrations

### 1. Visual Studio Code (Primary)
The extension syncs active file context and terminal errors.
* **Install:** Search for **"Vidurai"** in the VS Code Marketplace.
* **Handshake:** Automatically connects to the daemon on startup.

### 2. Cursor Editor (Native Support)
Cursor works natively via the VS Code extension ecosystem.
1. Download `vidurai-extension.vsix` from Releases.
2. **Install via Terminal** (Recommended for reliability):
   ```bash
   cursor --install-extension vidurai-extension.vsix
   ```

### 3. Claude Desktop (MCP)
Vidurai implements the Model Context Protocol.

**Config Location:**
- Linux/Mac: `~/.config/claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

**Config:**
```json
{
  "mcpServers": {
    "vidurai": {
      "command": "vidurai",
      "args": ["server"]
    }
  }
}
```

Or use the auto-installer:
```bash
vidurai mcp-install
```

---

## CLI Reference (v2.2.0)

> Full reference: [docs/CLI.md](docs/CLI.md) (auto-generated via AST static analysis)

### Daemon Control
| Command | Description |
| :--- | :--- |
| `vidurai start` | Start the Vidurai Guardian daemon (background service). |
| `vidurai stop` | Stop the Vidurai Guardian daemon. |
| `vidurai status` | Show Vidurai Guardian daemon status. |
| `vidurai logs` | Show or follow the Vidurai daemon logs (`-f` to follow). |
| `vidurai info` | Show Vidurai installation information. |

### Memory Operations
| Command | Description |
| :--- | :--- |
| `vidurai recall` | Recall memories from project database. |
| `vidurai recent` | Show recent development activity. |
| `vidurai context` | Get formatted context for AI tools (Claude Code, ChatGPT, etc.) |
| `vidurai stats` | Show memory statistics for a project. |
| `vidurai hygiene` | Memory hygiene - Review and archive low-utility memories. |
| `vidurai hints` | Show proactive hints based on your development history. |

### Strategic Forgetting (SF-V2)
| Command | Description |
| :--- | :--- |
| `vidurai pin` | Pin a memory to prevent it from being forgotten. |
| `vidurai unpin` | Unpin a memory to allow forgetting. |
| `vidurai pins` | List all pinned memories. |
| `vidurai forgetting-log` | Show forgetting event log for transparency. |
| `vidurai forgetting-stats` | Show forgetting statistics. |

### Import & Export
| Command | Description |
| :--- | :--- |
| `vidurai ingest` | Ingest historical AI conversations (Ghost in the Shell). |
| `vidurai export` | Export project memories to JSON/Text. |
| `vidurai get-context-json` | Get project context as JSON (stdout only, for piping). |

### Advanced & Debug
| Command | Description |
| :--- | :--- |
| `vidurai audit` | Audit code for security risks. |
| `vidurai fix` | Agentic Fixer (Shadow Mode). Safely modifies code in isolation. |
| `vidurai chat` | Start the interactive Vidurai Voice session (REPL). |
| `vidurai server` | Start MCP server for AI tool integration. |
| `vidurai mcp-install` | Install Vidurai as MCP server for Claude Desktop. |
| `vidurai clear` | Clear all memories for a project (irreversible!). |

---

## Architecture

```
+-------------------------------------------------------------+
|                      YOUR MACHINE                           |
+-------------------------------------------------------------+
|                                                             |
|   +-----------+         +-----------------------------+     |
|   |  VS Code  |<--IPC-->|                             |     |
|   | Extension |         |    Vidurai Guardian         |     |
|   +-----------+         |    (Background Daemon)      |     |
|                         |                             |     |
|   +-----------+         |  +-----------------------+  |     |
|   |  Claude   |<--MCP-->|  |  Context Mediator    |  |     |
|   |  Desktop  |         |  |  (Semantic Compress) |  |     |
|   +-----------+         |  +-----------------------+  |     |
|                         |            |                |     |
|   +-----------+         |  +---------v-----------+    |     |
|   |  Cursor   |<--IPC-->|  |  Memory Store       |    |     |
|   |  Editor   |         |  |  (SQLite + Parquet) |    |     |
|   +-----------+         |  +---------------------+    |     |
|                         |                             |     |
|                         +-----------------------------+     |
|                                                             |
+-------------------------------------------------------------+
```

### Storage Stack
* **Hot Storage:** SQLite (Metadata) + sqlite-vec (Embeddings)
* **Cold Storage:** Apache Parquet (Archives)
* **Privacy:** All data in `$HOME/.vidurai`. PII (API Keys) redacted via Regex Gatekeeper.
* **Learning:** Offline Reinforcement Learning (RL) prunes low-salience context.

### Data Directory
```
~/.vidurai/
├── memory.db          # SQLite database (hot storage)
├── vidurai.log        # Daemon logs (rotated, max 50MB)
├── daemon.pid         # Process ID file
└── archive/           # Parquet files (cold storage)
    └── YYYY/MM/       # Partitioned by date
```

---

## Quick Verification

```bash
# Check daemon status
vidurai status

# View recent logs
vidurai logs -n 20

# Search memories
vidurai recall --query "authentication"

# Check memory health
vidurai hygiene
```

---

## Documentation

| Document | Description |
|----------|-------------|
| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common issues and solutions |
| [docs/SECURITY.md](docs/SECURITY.md) | Security policy and PII redaction |
| [docs/CLI.md](docs/CLI.md) | Auto-generated CLI reference |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution guidelines |

---

## License

MIT License. See [LICENSE](LICENSE) for details.

---

**Vidurai** — *Because your AI should remember what you've already solved.*

<div align="center">
  <sub>विस्मृति भी विद्या है (Forgetting too is knowledge)</sub>
</div>
