https://github.com/chandantochandan/vidurai
Local-first context infrastructure. Semantic compression (SF-V2) and temporal memory for developer workflows.
https://github.com/chandantochandan/vidurai
context-engine developer-tools local-first middleware python rag semantic-compression
Last synced: 6 months ago
JSON representation
Local-first context infrastructure. Semantic compression (SF-V2) and temporal memory for developer workflows.
- Host: GitHub
- URL: https://github.com/chandantochandan/vidurai
- Owner: chandantochandan
- Created: 2025-10-29T19:33:06.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-11-30T07:09:29.000Z (6 months ago)
- Last Synced: 2025-12-01T17:19:23.975Z (6 months ago)
- Topics: context-engine, developer-tools, local-first, middleware, python, rag, semantic-compression
- Language: Python
- Homepage: https://vidurai.ai/
- Size: 1.8 MB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Audit: audit_reports/PROMPT_02_GISTING_SYSTEMS.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
Vidurai
Local-First Context Infrastructure & Semantic Compression Engine
[](https://pypi.org/project/vidurai/)
[](https://github.com/chandantochandan/vidurai/blob/main/LICENSE)
---
Vidurai is **local-first context middleware** that solves the *context window bottleneck* in LLM-driven workflows.
It sits between **developer environments** (IDE, terminal, browser) and **AI models**, ingesting high-velocity telemetry (file edits, terminal commands, AI chats), normalizing it via a **Shared Event Schema**, and applying **SF-V2 semantic compression** to maintain a **high-signal temporal graph** of a project.
**Core capability:**
Reduce tokens by 50–70% for AI prompts while preserving 100% of critical technical entities (file paths, stack traces, function names).
---
## 1. Engineering Problem
Raw developer activity is high-entropy:
- **IDE:** rapid file saves, refactors, and diagnostics
- **Terminal:** command spam, noisy logs
- **Browser:** ad-hoc AI chats with half-remembered context
Feeding these directly into an LLM causes:
1. **Context saturation** – token limits hit long before the real history is represented.
2. **State fragmentation** – VS Code, terminal, and browser all have partial views.
3. **Hallucinations** – the model optimizes on recent noise instead of actual project state.
4. **Runaway cost** – you pay for the same story over and over again.
**Vidurai's role:**
Act as a **local context layer** that continuously ingests signals, compresses them into durable "episodes", and serves **audience-specific context** back to tools and agents on demand.
---
## 2. Architecture Overview (v2.0.0)
```text
[VS Code] [Browser UI] [Terminal]
│ │ │
(WebSocket) (WebSocket) (StdOut)
│ │ │
▼ ▼ ▼
┌────────────────────────────────────────────────┐
│ Vidurai Daemon (Local) │
│ [Normalizer] → [SF-V2 Engine] → [SQLite/WAL] │
└───────────────────────┬────────────────────────┘
│ (HTTP / JSON)
┌───────────┴───────────┐
▼ ▼
[Python SDK / CLI] [LLM Proxy]
(Context Retrieval) (Prompt Injection)
```
### Components
#### 1. Vidurai SDK (this package)
- Pydantic models for the Shared Event Schema
- SF-V2 semantic compression engine
- Local project client (`VismritiMemory`)
- CLI tooling (`vidurai …`)
#### 2. Vidurai Daemon (hub service)
- **Stack:** Python 3.9+, FastAPI, AsyncIO
- Runs on `localhost:7777`
- Ingests events from VS Code / Browser / CLI
- Performs entity extraction (paths, symbols, errors, IDs)
- Applies SF-V2 scoring + consolidation
- Persists to SQLite (`~/.vidurai/vidurai.db`, WAL mode)
#### 3. VS Code Extension (sensor)
- Watches file edits, terminal commands, and diagnostics
- Emits structured `ViduraiEvent` messages to the daemon
- Exposes "Copy Context for AI" command for one-click prompt injection
#### 4. Browser Extension (sensor)
- Targets AI chat UIs (ChatGPT, Claude, Gemini, etc.)
- Captures prompts + responses as events
- Injects Vidurai context into new chats via hotkey / UI actions
#### 5. LLM Proxy (optional)
- HTTP proxy around LLM APIs
- Automatically attaches Vidurai gists to outbound prompts
- Enables context-aware CLI tools, scripts, or agents
---
## 3. Shared Event Schema
All tools speak the same language: `ViduraiEvent`.
```json
{
"schema_version": "vidurai-events-v1",
"event_id": "d8c8a3f2-9c25-4e2a-9a4d-3f2e91f4b7a1",
"timestamp": "2025-11-26T18:30:00.123Z",
"source": "vscode",
"channel": "human",
"kind": "file_edit",
"project_root": "/home/user/vidurai",
"project_id": "proj_8f21b9a0",
"session_id": "sess_02c9b1d4",
"payload": {
"file_path": "vidurai/core/sf_v2.py",
"language": "python",
"change_type": "modified",
"summary": "Refactor scoring function"
}
}
```
Backed by:
- **Python:** `vidurai.shared.events` (`ViduraiEvent`, `EventKind`, etc.)
- **TypeScript:** `src/shared/events.ts` in VS Code + browser extensions
This schema is the contract between all sensors and the daemon.
---
## 4. SF-V2 Semantic Compression
Vidurai does not append logs forever.
SF-V2 runs a deterministic pipeline:
1. **Window selection** – select a time/window slice of events for a project.
2. **Role classification** – label events as `CAUSE`, `ATTEMPT`, `FIX`, `NOISE`, etc.
3. **Scoring** – compute retention scores using recency, frequency, and structural importance.
4. **Consolidation** – merge low-value events into summaries while preserving hard entities (paths, line numbers, symbols, IDs).
5. **Episode creation** – store high-density "episodes" that reflect how the project changed.
Outputs are then exposed as **gists**:
| Audience | Purpose |
|----------|---------|
| `AI` | token-bounded, machine-optimized context for LLM calls |
| `DEVELOPER` | richer textual summary for humans |
| `MANAGER` / `STAKEHOLDER` | higher-level progress narratives |
---
## 5. Security & Data Governance
Vidurai is built for zero-trust environments:
### Local-first storage
- Data lives in `~/.vidurai/` by default (SQLite + JSONL ledgers).
- No mandatory cloud component.
### Ingestion-time redaction
- Pluggable regex filters to mask API keys, tokens, and secrets before persistence.
### Transparency
- Every compression / deletion decision is logged to a `forgetting_ledger.jsonl` for audit and debugging.
- Nothing leaves the machine unless you explicitly configure a remote proxy or sync mechanism.
---
## 6. Installation & Deployment
### 6.1 Python SDK
```bash
pip install vidurai
```
Requires Python 3.9+.
### 6.2 Daemon (recommended: Docker)
```bash
docker run --rm -d \
-p 7777:7777 \
-v ~/.vidurai:/root/.vidurai \
chandantochandan/vidurai-daemon:2.0.0
```
This starts the Vidurai Daemon on `http://localhost:7777` with persistent state in `~/.vidurai`.
### 6.3 Optional: LLM Proxy
```bash
docker run --rm -d \
-p 9999:9999 \
-v ~/.vidurai:/root/.vidurai \
chandantochandan/vidurai-proxy:2.0.0
```
Use this if you want Vidurai gists automatically injected into outbound LLM API calls.
---
## 7. SDK Usage Example
```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="Refactored authentication module to use JWT tokens",
tags=["refactor", "auth", "jwt"],
metadata={"file": "auth/jwt_handler.py", "line": 42}
)
# 3. Recall relevant context
results = memory.recall(
query="authentication implementation",
limit=5
)
for mem in results:
print(f"[{mem.salience}] {mem.gist}")
# 4. Get compressed context for AI prompt injection
context = memory.get_context(
query="current auth flow",
max_tokens=2000
)
print(f"Injecting context into LLM prompt:")
print(context)
```
Typical uses:
- Pre-pend context to prompts for ChatGPT/Claude/Gemini.
- Feed specialized gists into autonomous agents / tools.
- Generate manager-friendly status summaries.
---
## 8. Integrations
### VS Code Extension
- **Marketplace ID:** `vidurai.vidurai`
- Sends `file_edit`, `terminal_command`, and `diagnostics` events to the daemon.
- Provides "Copy Vidurai Context" command for pasting into AI chats.
### Browser Extension
- Chrome MV3 extension (Universal AI Context).
- Targets major AI UIs (ChatGPT, Claude, Gemini, etc.).
- Can inject Vidurai context into new conversations.
### CLI / Scripts
- Use the SDK or HTTP API to pull audience-specific gists and attach them to prompts in custom tools or agents.
---
## 9. Versioning & Legacy RL Engine
- **Current release:** v2.0.0 – unified architecture around SF-V2 + shared events.
- **Legacy RL-based v1.x:** preserved for reference in `docs/archive/implementation/`.
The v2 line focuses on deterministic semantic compression and event-driven context, not on generic RL experimentation.
---
## 10. Repository Layout
```
vidurai/ # Python SDK (this package)
vidurai-daemon/ # Local hub service
vidurai-vscode-extension/ # VS Code telemetry extension
vidurai-browser-extension/ # Browser AI context extension
vidurai-proxy/ # Optional LLM proxy
tests/ # SDK tests
docs/ # Documentation
└── archive/
└── implementation/ # Historical PHASE_* docs
ARCHITECTURE_OVERVIEW.md # High-level system architecture
CHANGELOG.md # Version history
```
---
## 11. Links
- **Website:** https://vidurai.ai
- **Docs:** https://docs.vidurai.ai
- **Source:** https://github.com/chandantochandan/vidurai
- **Issues:** https://github.com/chandantochandan/vidurai/issues
- **Docker Hub:** https://hub.docker.com/u/chandantochandan
---
## 12. License
Vidurai is released under the **MIT License**.
See the [LICENSE](https://github.com/chandantochandan/vidurai/blob/main/LICENSE) file for details.