# Domicile

> Your data, domiciled on your device. A private AI stack — vector database, RAG, and local LLM — that runs entirely in the browser. Zero egress, zero third-party processors.

- **Type:** MCP server
- **Install:** `agentstack add mcp-kyrillosishak-domicile`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kyrillosishak](https://agentstack.voostack.com/s/kyrillosishak)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kyrillosishak](https://github.com/kyrillosishak)
- **Source:** https://github.com/kyrillosishak/Domicile
- **Website:** https://kyrillosishak.github.io/Domicile/

## Install

```sh
agentstack add mcp-kyrillosishak-domicile
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

**Your data, domiciled on your device.**

On-prem privacy, in the browser — vector database, RAG, and local LLM. 

All processing stays client-side, with zero egress.

[](https://www.npmjs.com/package/@kyrillosishak/domicile)
[](./LICENSE)

---

## Why Domicile?

Domicile is a private AI stack — vector database, RAG, and a local LLM that runs entirely in the browser. On-prem-grade data custody and privilege protection, without the on-prem infrastructure. Your documents never leave their legal residence.

- **Private**: Data never leaves the device — zero egress, zero third-party processors
- **Fast**: WebGPU acceleration with WASM SIMD fallback
- **Free**: Zero cloud costs, no API keys, no per-seat fees
- **Complete**: Vector DB + embeddings + dual LLM + RAG with citations
- **Offline**: Works without internet after initial load

## Quick Start

```bash
npm install @kyrillosishak/domicile
```

```typescript
import Domicile from '@kyrillosishak/domicile';

// A private, in-browser custody layer
const db = new Domicile({
  storage:   { dbName: 'matter-files' },
  index:     { dimensions: 384, metric: 'cosine' },
  embedding: { model: 'Xenova/all-MiniLM-L6-v2', device: 'webgpu' },
});

await db.initialize();

await db.insert({
  text: 'Privileged communication — attorney work product',
  metadata: { matter: 'M-204', privilege: 'true' },
});

const results = await db.search({ text: 'summary of work product', k: 5 });
console.log(results);
```

## Features

- **Vector Database**: Persistent client-side storage in IndexedDB with a pure-TypeScript HNSW graph index. Hold and search 100K+ documents with cosine, euclidean or dot metrics — real similarity scores, non-rebuilding deletes — all in residence on the device.
- **Local Embeddings**: Transformers.js with WebGPU acceleration and a WASM fallback. Model weights cached on-device, so repeat queries never reach the network.
- **Dual LLM Runtime**: WebLLM for GPU-fast inference, Wllama for CPU portability — automatic fallback so generation works on any workstation.
- **RAG with Citations**: Answers grounded in your source documents, with citations linking every claim back to the document that grounded it — auditable, not black-box.
- **MCP Integration**: Expose your custody layer as Model Context Protocol tools — wire Domicile into Claude Desktop and the agent stacks your team already builds on.
- **Resident by Design**: Data domiciled on the device — no cloud egress, no third-party processors, no residency drift. The boundary is architectural, not a configuration someone can forget to check.

## For Whom

**Law Firms & Legal Teams** — Sensitive matter files, privileged communications, and client data never leave the workstation. Domicile runs RAG and generation locally, so attorney-client privilege is never routed through a third-party cloud. GDPR-compliant by construction, works offline.

**Integration & Infra Teams** — The custody layer you offer clients who want on-prem guarantees without on-prem capital expense. Ship it inside their app, configure residency, walk away — no servers to run, no data plane to secure.

## Core Features

### Vector Search
```typescript
// Retrieval with metadata filtering
const results = await db.search({
  text: 'indemnification clauses',
  k: 10,
  filter: { field: 'matter', operator: 'eq', value: 'M-204' },
});

for (const r of results) {
  console.log(r.score.toFixed(3), r.metadata);
}

// Inspect custody state
const stats: IndexStats = await db.stats();
console.log(stats.vectorCount, stats.memoryUsage);
```

### RAG Pipeline
```typescript
import { RAGPipelineManager, WllamaProvider } from '@kyrillosishak/domicile';

const llm = new WllamaProvider({ model: '...' });
const rag = new RAGPipelineManager(db, llm, embedding);

// Ask questions grounded in your documents
const result = await rag.query('Summarize the position.', {
  topK: 3,
  generateOptions: { maxTokens: 256, temperature: 0.7 },
});

console.log(result.answer);
console.log(result.sources); // Cited source documents
```

### MCP Integration
```typescript
import { MCPServer } from '@kyrillosishak/domicile';

// Expose your custody layer as tools for AI agents
const mcp = new MCPServer(db, rag);

const tools: MCPTool[] = mcp.getTools();
// → [search, insert, rag_query, ...]

// Wire into Claude Desktop or any MCP-aware agent
mcp.serve({ transport: 'stdio' });
```

## Architecture

A layered, resident-by-design stack. Each layer is swappable and runs without a server. Data flows down; answers flow up — all on the device.

- **Interface**: Your application talks to a clean TypeScript API, or to AI agents over MCP — Claude Desktop, ChatGPT, anything that speaks the protocol.
- **Intelligence**: The RAG pipeline manager orchestrates retrieval and generation, with WebLLM and Wllama runtimes and automatic GPU-to-CPU fallback.
- **Retrieval**: Transformers.js produces embeddings; the pure-TS HNSW index returns nearest neighbours with real scores. A BM25 sparse index fuses with dense via reciprocal-rank fusion, and a cross-encoder reranker sharpens the top-k — all filtered by metadata.
- **Custody**: IndexedDB storage manager with quota-aware eviction and JSON/binary export-import for migration and client hand-off.
- **Acceleration**: GPU compute when WebGPU is available, WASM SIMD fallback otherwise, with a worker pool for batched parallelism.
- **Reliability**: A typed error hierarchy, LRU caches, a memory manager, and a built-in benchmark runner to measure it all.

```mermaid
graph TB
    subgraph "Interface"
        APP[User Application]
        MCP[MCP Interface]
    end
    
    subgraph "Intelligence"
        API[VectorDB API]
        RAG[RAG Pipeline Manager]
    end
    
    subgraph "Retrieval"
        TJS[Transformers.js]
        CACHE[Model Cache]
    end
    
    subgraph "LLM Layer"
        WLLAMA[wllama - WASM]
        WEBLLM[WebLLM - WebGPU]
    end
    
    subgraph "Index Layer"
        HNSW[HNSW Graph Index]
        BM25[BM25 Sparse Index]
    end
    
    subgraph "Custody"
        IDB[IndexedDB]
        STORE[Storage Manager]
    end
    
    APP --> API
    MCP --> API
    API --> RAG
    API --> HNSW
    RAG --> TJS
    RAG --> WLLAMA
    RAG --> WEBLLM
    TJS --> CACHE
    HNSW --> STORE
    STORE --> IDB
```

## Performance

Reproducible from `domicile bench` — the same suite that gates the build. Measured on a Linux/server CPU (Node); a browser WebGPU run will differ.

| Operation | Latency | Throughput / Quality | Notes |
|-----------|---------|----------------------|-------|
| Search (10K vectors, 128-dim cosine) | p50 2.4ms / p99 7ms | recall@10 = 0.91 | Pure-TS HNSW, warm cache |
| Search (1K vectors, 128-dim cosine) | p50 1.4ms / p99 1.8ms | recall@10 = 1.00 | Non-rebuilding delete 

**[Documentation](./docs/QUICKSTART.md)** • **[Examples](./examples/README.md)** • **[GitHub](https://github.com/kyrillosishak/Domicile)**

Built for privacy-conscious legal and integration teams

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kyrillosishak](https://github.com/kyrillosishak)
- **Source:** [kyrillosishak/Domicile](https://github.com/kyrillosishak/Domicile)
- **License:** MIT
- **Homepage:** https://kyrillosishak.github.io/Domicile/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-kyrillosishak-domicile
- Seller: https://agentstack.voostack.com/s/kyrillosishak
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.