Metadata-Version: 2.4
Name: vidurai
Version: 2.0.0
Summary: Vidurai — Local-First AI Memory & Context Engine (SF-V2)
Author: Chandan Kumar
License-Expression: MIT
Project-URL: Homepage, https://vidurai.ai
Project-URL: Documentation, https://docs.vidurai.ai
Project-URL: Source, https://github.com/chandantochandan/vidurai
Project-URL: Bug Tracker, https://github.com/chandantochandan/vidurai/issues
Project-URL: Changelog, https://github.com/chandantochandan/vidurai/blob/main/CHANGELOG.md
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.0.0
Requires-Dist: watchdog>=3.0.0
Requires-Dist: loguru>=0.7.0

<div align="center">
  <img src="https://raw.githubusercontent.com/chandantochandan/vidurai/main/assets/brand/logo_primary_512.png" alt="Vidurai Logo" width="180" />
  <h1>Vidurai</h1>
  <p>Local-First AI Memory &amp; Context Engine (SF-V2)</p>
</div>

> **"विस्मृति भी विद्या है"** — Forgetting too is knowledge.

[![PyPI version](https://img.shields.io/pypi/v/vidurai.svg)](https://pypi.org/project/vidurai/)
![Python versions](https://img.shields.io/pypi/pyversions/vidurai.svg)
[![License](https://img.shields.io/pypi/l/vidurai.svg)](https://github.com/chandantochandan/vidurai/blob/main/LICENSE)

---

Vidurai is a **local-first memory layer for AI**, purpose-built for developers who use AI assistants daily.

It sits between you and your AI tools (VS Code, terminal, ChatGPT / Claude / Gemini in the browser, LLM APIs) and builds a **compressed, structured project memory** from real activity — not just chat logs.

Instead of storing everything forever (like typical vector DB systems), Vidurai uses **Smart Forgetting (SF-V2)** to:

- retain high-signal events
- remove noise over time
- maintain a "spine" of the project
- generate **multi-audience gists** (developer, AI, manager, stakeholder)

Vidurai is **not** a single-app plugin.
It is a **universal context engine** for human–AI workflows.

---

## Why Vidurai?

**Most AI workflows today:**

- ❌ Forget everything between sessions
- ❌ Require constant re-explaining
- ❌ Burn tokens on unnecessary context
- ❌ Don't understand your project's evolution

**Vidurai changes this:**

- ✅ Watches **real developer behavior**
- ✅ Uses a **Shared Event Schema** to normalize all inputs
- ✅ Stores context locally inside a project-specific brain
- ✅ Runs **Smart Forgetting (SF-V2)** to reduce entropy
- ✅ Serves **audience-specific context** on demand

**Result:**
Your AI behaves like a **project-aware collaborator**, not a stateless intern.

---

## High-Level Architecture (v2.0.0)

```text
       [VS Code]      [Browser UI]      [Terminal]
           │               │                │
           ▼               ▼                ▼
    ┌──────────────────────────────────────────────┐
    │           Vidurai Daemon (Local)             │
    │  [Normalizer] -> [SF-V2 Engine] -> [DB]      │
    └──────────────────────┬───────────────────────┘
                           │
             ┌─────────────┴─────────────┐
             ▼                           ▼
      [SDK / CLI]                 [LLM Proxy]
   (Audience Gists)            (Context Injection)
```

Vidurai v2.0.0 consists of five core components:

### Python SDK (this PyPI package)

- Smart Forgetting (SF-V2) primitives
- Project memory storage
- Forgetting ledger
- Shared Event Schema (Pydantic models)
- `vidurai` CLI
- Local data directory: `~/.vidurai/`

### Vidurai Daemon (local background service)

- Receives events from VS Code, Browser, Proxy, CLI
- Normalizes them into the shared schema
- Applies SF-V2 policies
- Stores context in the local project brain
- Serves gists via a local HTTP API (default `localhost:7777`)

### VS Code Extension

- Captures file edits
- Captures terminal commands
- Captures diagnostics (errors / warnings)
- Streams events to the Daemon

### Browser Extension

- Captures prompts and replies from ChatGPT, Claude, Gemini, etc.
- Tracks AI conversations alongside code changes
- Supports context / gist injection into AI chats

### LLM Proxy (optional)

- Wraps LLM API calls
- Injects Vidurai context automatically
- Useful for script / CLI / server-side workflows

---

## Shared Event Schema

Every Vidurai tool emits events using the same structure:

```json
{
  "schema_version": "vidurai-events-v1",
  "event_id": "uuid",
  "timestamp": "2025-11-26T18:30:00.123Z",
  "source": "vscode | browser | daemon | proxy | cli",
  "channel": "human | ai | system",
  "kind": "file_edit | terminal_command | diagnostic | ai_message | ai_response | memory_event | metric_event | system_event",
  "project_root": "/abs/path",
  "project_id": "stable-project-hash",
  "session_id": "session-uuid",
  "payload": { "...kind-specific fields..." }
}
```

- Python models live inside the SDK: `vidurai.shared.events`
- TypeScript models live inside the VS Code and Browser extensions
- All are generated from the canonical spec shared across tools

---

## Smart Forgetting (SF-V2)

Vidurai does **not** store everything.

SF-V2 applies a biologically inspired forgetting model:

- **Dual-trace memory** (verbatim + gist)
- **Retention scoring** (importance, recency, access patterns)
- **Salience models** (what actually matters)
- **Access frequency tracking**
- **Selective forgetting** with a transparent ledger
- **Manual pinning** for critical memories

Over time, the memory becomes **sharper**, not bigger.

---

## Multi-Audience Context

Vidurai can produce different summaries for different consumers:

| Audience | Content |
|----------|---------|
| `developer` | files, diffs, errors, terminal commands |
| `ai` | token-efficient context chunks optimized for LLM input |
| `manager` | "what changed?" summaries and progress updates |
| `stakeholder` | impact, risk, high-level narrative |

You choose the audience per query.
The Daemon and SDK cooperate to generate the appropriate gist for each audience.

---

## Installation

### 1. Install the Python SDK

```bash
pip install vidurai
```

Requires Python 3.9+.

### 2. Run the Vidurai Daemon

**A. Docker (recommended)**

```bash
docker run --rm -p 7777:7777 \
  -v ~/.vidurai:/root/.vidurai \
  chandantochandan/vidurai-daemon:2.0.0
```

**B. From source**

```bash
cd vidurai-daemon
pip install .
python daemon.py
```

### 3. (Optional) Run the LLM Proxy

```bash
docker run --rm -p 9999:9999 \
  chandantochandan/vidurai-proxy:2.0.0
```

### 4. Connect Tools

**VS Code**

Install the extension from the Marketplace:
`ID: vidurai.vidurai`

**Browser**

Load the "Vidurai – Universal AI Context" extension in developer mode
or install from Chrome Web Store once published.

Once connected, the extensions start streaming events to the Daemon.

---

## Using the SDK

The SDK exposes helpers to talk to the local project brain and retrieve SF-V2 gists.

> **Note:** The exact class and method names may evolve.
> Always refer to the latest API reference or `vidurai` package source.

Example shape of a typical integration:

```python
from vidurai.vismriti_memory import VismritiMemory

# 1. Initialize memory for a project
memory = VismritiMemory(project_path=".")

# 2. Store a memory with automatic salience detection
memory.remember(
    gist="Fixed authentication bug in /api/auth endpoint",
    tags=["bugfix", "auth"],
    metadata={"file": "auth.py", "line": 42}
)

# 3. Recall relevant context
results = memory.recall(
    query="authentication issues",
    limit=5
)

for mem in results:
    print(f"[{mem.salience}] {mem.gist}")

# 4. Get project context for AI injection
context = memory.get_context(
    query="current auth implementation",
    max_tokens=2000
)
print(context)
```

This allows you to:

- inject compressed contexts into LLM prompts
- generate high-level updates for humans
- query recent project and conversation changes

---

## Local-First & Privacy

Vidurai is designed around **local-first privacy**:

- All data lives under `~/.vidurai/`
- The Daemon runs on `localhost`
- There is **no cloud dependency** by default
- Any future remote / team sync will always be **opt-in**, explicit, and documented

You control:

- what is stored
- which projects are tracked
- when to clear memory

---

## Migration from v1.x

Vidurai v2.0.0 is a **major architecture update**.

**Key changes:**

- RL-centric v1.x design is now considered legacy
- Kosha-based classes are deprecated in favor of SF-V2 and the shared schema
- Daemon, SDK, Proxy, and extensions are aligned around a unified event model
- Storage layout and configuration have been simplified

**To upgrade:**

```bash
pip uninstall vidurai
pip install vidurai
```

Then reinstall / upgrade:

- Daemon
- VS Code extension
- Browser extension

Legacy design documents are preserved under:

```
docs/archive/implementation/
```

for historical reference.

---

## Repository Layout

```
vidurai/                     # Python SDK (this PyPI package)
vidurai-daemon/              # Daemon service
vidurai-vscode-extension/    # VS Code extension
vidurai-browser-extension/   # Browser extension
vidurai-proxy/               # Optional LLM proxy
tests/                       # SDK tests
docs/                        # Documentation
docs/archive/implementation/ # Historical PHASE_* docs
ARCHITECTURE_OVERVIEW.md     # Canonical system architecture
CHANGELOG.md                 # Version history
AGENTS.md                    # AI agent protocol
BRAND.md                     # Brand & visual identity rules
active_context.md            # Current project state
```

---

## Links

- **Website:** https://vidurai.ai
- **Docs:** https://docs.vidurai.ai
- **Source:** https://github.com/chandantochandan/vidurai
- **Bug Tracker:** https://github.com/chandantochandan/vidurai/issues
- **Changelog:** https://github.com/chandantochandan/vidurai/blob/main/CHANGELOG.md
- **Docker Hub:** https://hub.docker.com/u/chandantochandan

---

## License

Vidurai is released under the **MIT License**.
See the [LICENSE](https://github.com/chandantochandan/vidurai/blob/main/LICENSE) file for details.
