Metadata-Version: 2.4
Name: vault-sync-ai
Version: 0.1.0
Summary: E2E encrypted portable AI memory — your context travels with you
Project-URL: Homepage, https://github.com/shubhamdusane/vault-sync
Project-URL: Repository, https://github.com/shubhamdusane/vault-sync
Project-URL: Issues, https://github.com/shubhamdusane/vault-sync/issues
Author-email: Shubham Dusane <sdusane4@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai,crdt,encryption,langchain,memory,privacy,sync
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: cryptography>=41.0.0; extra == 'all'
Requires-Dist: langchain>=0.2.0; extra == 'all'
Requires-Dist: pynacl>=1.5.0; extra == 'all'
Provides-Extra: crypto
Requires-Dist: pynacl>=1.5.0; extra == 'crypto'
Provides-Extra: crypto-fallback
Requires-Dist: cryptography>=41.0.0; extra == 'crypto-fallback'
Provides-Extra: langchain
Requires-Dist: langchain>=0.2.0; extra == 'langchain'
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# vault-sync

<p align="center">
  <strong>End-to-end encrypted portable AI memory with CRDT sync</strong>
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> •
  <a href="#installation">Installation</a> •
  <a href="#api-reference">API Reference</a> •
  <a href="#architecture">Architecture</a> •
  <a href="#contributing">Contributing</a>
</p>

---

## What is vault-sync?

vault-sync is a **portable, encrypted memory layer** for AI applications. It lets you store, retrieve, and sync conversations, facts, and context across devices and sessions—without ever exposing your data in plaintext.

Think of it as a **personal brain for your AI**: it remembers what matters, keeps it private, and stays in sync across all your devices.

### Key Features

- **End-to-End Encryption** – Your data is encrypted locally with NaCl before it ever leaves your machine
- **CRDT Sync** – Conflict-free replicated data types enable seamless multi-device synchronization
- **Vector Clocks** – Precise causality tracking for perfect merge semantics
- **SQLite Storage** – Lightweight, zero-config, portable database
- **LangChain & Anthropic Ready** – First-class integrations with popular AI frameworks
- **22 Passing Tests** – Battle-tested reliability

---

## The Problem: AI Amnesia

Every time you start a new conversation with an AI, it forgets everything. Your preferences, your context, your history—gone.

```
Today: "I prefer dark mode and use Python 3.12"
Tomorrow: "What's my preference?" → "I don't know you"
```

**vault-sync solves this** by giving your AI a persistent, encrypted memory that travels with you.

---

## How It Works

### Encryption Flow

Your data is encrypted client-side before storage:

```
┌─────────────────────────────────────────────────────────────┐
│                     ENCRYPTION FLOW                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────┐    ┌──────────────┐    ┌──────────────────┐   │
│  │ plaintext│───▶│ VaultCrypto  │───▶│ encrypted_blob   │   │
│  │  (JSON)  │    │  (NaCl/box)  │    │  (stored in DB)  │   │
│  └──────────┘    └──────────────┘    └──────────────────┘   │
│       │                │                     │               │
│       │                ▼                     │               │
│       │         ┌──────────────┐             │               │
│       │         │  Per-device  │             │               │
│       │         │  key pairs   │             │               │
│       │         └──────────────┘             │               │
│       │                                      │               │
│       ▼                                      ▼               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              Encrypted SQLite Store                   │   │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐              │   │
│  │  │ memory1 │  │ memory2 │  │ memory3 │  ...          │   │
│  │  └─────────┘  └─────────┘  └─────────┘              │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### CRDT Sync

Conflicts are resolved automatically using vector clocks:

```
┌─────────────────────────────────────────────────────────────┐
│                       CRDT SYNC                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Device A                    Device B                       │
│  ┌─────────────┐            ┌─────────────┐                │
│  │ VC: {A:3}   │            │ VC: {A:2,B:1}│                │
│  │ memories... │            │ memories... │                │
│  └──────┬──────┘            └──────┬──────┘                │
│         │                          │                        │
│         │    ┌────────────────┐    │                        │
│         └───▶│  Sync Manager  │◀───┘                        │
│              │                │                             │
│              │  1. Merge VCs  │                             │
│              │  2. Resolve    │                             │
│              │     conflicts  │                             │
│              │  3. Replicate  │                             │
│              └───────┬────────┘                             │
│                      │                                      │
│                      ▼                                      │
│              ┌──────────────┐                               │
│              │  Merged VC:  │                               │
│              │  {A:3, B:1}  │                               │
│              └──────────────┘                               │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Vector Clock Tracking

Every mutation is tracked with a vector clock for perfect causality:

```
┌─────────────────────────────────────────────────────────────┐
│                    VECTOR CLOCKS                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Timeline:                                                  │
│                                                             │
│  t1: {A:1}          → Device A writes                       │
│  t2: {A:1, B:1}     → Device B joins                        │
│  t3: {A:2, B:1}     → Device A writes again                 │
│  t4: {A:2, B:2}     → Device B writes                       │
│  t5: {A:3, B:2}     → Device A writes (concurrent?)         │
│                                                             │
│  Merge at t5:                                               │
│  ┌────────────────────────────────────────────────────┐     │
│  │  If VC(A) > VC(B): A wins                         │     │
│  │  If VC(B) > VC(A): B wins                         │     │
│  │  If concurrent:    last-write-wins by timestamp    │     │
│  └────────────────────────────────────────────────────┘     │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## Installation

```bash
# From PyPI (when published)
pip install vault-sync

# From source
git clone https://github.com/your-org/vault-sync.git
cd vault-sync
pip install -e ".[dev]"
```

### Requirements

- Python 3.10+
- SQLite 3.35+
- pynacl
- langchain (optional)
- anthropic (optional)

---

## Quick Start

```python
from vault_sync import VaultStore, VaultCrypto

# Initialize with encryption
crypto = VaultCrypto.generate_keypair()
store = VaultStore(crypto=crypto)

# Store a memory
store.put(
    key="user_preferences",
    value={"theme": "dark", "language": "en", "timezone": "UTC-5"},
    tags=["preferences", "ui"]
)

# Retrieve it
prefs = store.get("user_preferences")
print(prefs)  # {'theme': 'dark', 'language': 'en', 'timezone': 'UTC-5'}

# Search memories
results = store.search(query="dark mode")
```

---

## Python API Reference

### VaultStore

```python
class VaultStore:
    def __init__(self, crypto: VaultCrypto, db_path: str = "vault.db"):
        """Initialize the vault store with encryption keys."""

    def put(self, key: str, value: dict, tags: List[str] = None) -> str:
        """Store an encrypted memory. Returns the memory ID."""

    def get(self, key: str) -> Optional[dict]:
        """Retrieve and decrypt a memory by key."""

    def search(self, query: str = None, tags: List[str] = None) -> List[dict]:
        """Search memories by query or tags."""

    def delete(self, key: str) -> bool:
        """Delete a memory by key."""

    def list_all(self) -> List[dict]:
        """List all stored memories."""

    def sync(self, remote: 'VaultStore') -> SyncResult:
        """Sync with another vault store using CRDT merge."""
```

### VaultCrypto

```python
class VaultCrypto:
    @classmethod
    def generate_keypair(cls) -> 'VaultCrypto':
        """Generate a new NaCl keypair for encryption."""

    def encrypt(self, plaintext: bytes) -> bytes:
        """Encrypt data with the public key."""

    def decrypt(self, ciphertext: bytes) -> bytes:
        """Decrypt data with the private key."""

    def export_public_key(self) -> str:
        """Export the public key (safe to share)."""
```

### VectorClock

```python
class VectorClock:
    def __init__(self, node_id: str):
        """Initialize a vector clock for a specific node."""

    def increment(self) -> None:
        """Increment the local counter."""

    def merge(self, other: 'VectorClock') -> 'VectorClock':
        """Merge with another vector clock (takes element-wise max)."""

    def happens_before(self, other: 'VectorClock') -> bool:
        """Check if this event happened before another."""

    def concurrent_with(self, other: 'VectorClock') -> bool:
        """Check if events are concurrent."""
```

---

## LangChain Integration

Use vault-sync as a memory backend for LangChain:

```python
from langchain.memory import ConversationBufferMemory
from vault_sync.integrations.langchain import VaultSyncMemory

# Initialize with vault-sync backend
vault = VaultStore(crypto=crypto)
memory = VaultSyncMemory(vault=vault, return_messages=True)

# Use in a chain
from langchain.chains import ConversationChain
from langchain_anthropic import ChatAnthropic

llm = ChatAnthropic(model="claude-sonnet-4-20250514")
chain = ConversationChain(llm=llm, memory=memory)

# Conversations are automatically encrypted and stored
response = chain.predict(input="My name is Alice")
response = chain.predict(input="What's my name?")  # Remembers!
```

---

## Anthropic Integration

Direct integration with Anthropic's API:

```python
from vault_sync.integrations.anthropic import AnthropicMemory

# Initialize
memory = AnthropicMemory(vault=vault)

# Store facts
memory.store_fact("User prefers concise responses", importance="high")
memory.store_fact("User is working on a Python project", importance="medium")

# Retrieve context for a prompt
context = memory.get_context(limit=10)
system_prompt = f"Previous context:\n{context}\n\nRespond to the user."

# Use with Anthropic API
import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system=system_prompt,
    messages=[{"role": "user", "content": "Continue where we left off"}]
)
```

---

## Cross-Device Sync

vault-sync uses CRDTs to sync across devices without conflicts:

```python
from vault_sync import VaultStore, VaultCrypto, SyncManager

# Device A (laptop)
crypto_a = VaultCrypto.generate_keypair()
store_a = VaultStore(crypto=crypto_a, db_path="vault_a.db")
store_a.put("note", {"content": "Meeting at 3pm"})

# Device B (phone) - shares the same public key
crypto_b = VaultCrypto.from_public_key(crypto_a.export_public_key())
store_b = VaultStore(crypto=crypto_b, db_path="vault_b.db")

# Sync
sync_manager = SyncManager()
result = sync_manager.sync(store_a, store_b)

print(result.merged)      # 1
print(result.conflicts)   # 0 (CRDTs resolve automatically)
print(result.clock)       # {'A': 1, 'B': 0}
```

### Sync Modes

| Mode | Description | Use Case |
|------|-------------|----------|
| `push` | Send local changes to remote | Upload from device |
| `pull` | Fetch remote changes | Download to device |
| `bidirectional` | Full two-way sync | Default sync |

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    ARCHITECTURE                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                   Application Layer                   │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐   │   │
│  │  │   LangChain │  │  Anthropic  │  │   Custom    │   │   │
│  │  │ Integration │  │ Integration │  │     App     │   │   │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘   │   │
│  └─────────┼────────────────┼────────────────┼───────────┘   │
│            │                │                │               │
│            ▼                ▼                ▼               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                   Core Layer                          │   │
│  │  ┌──────────────────────────────────────────────┐    │   │
│  │  │              VaultStore                       │    │   │
│  │  │  • put / get / delete / search / list_all    │    │   │
│  │  │  • sync (CRDT merge)                         │    │   │
│  │  └──────────────────────────────────────────────┘    │   │
│  └──────────────────────────────────────────────────────┘   │
│                           │                                 │
│            ┌──────────────┼──────────────┐                  │
│            ▼              ▼              ▼                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ VaultCrypto │  │ VectorClock │  │  SyncManager│         │
│  │             │  │             │  │             │         │
│  │ • encrypt   │  │ • merge     │  │ • push      │         │
│  │ • decrypt   │  │ • compare   │  │ • pull      │         │
│  │ • keypairs  │  │ • track     │  │ • bidir     │         │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
│         │                │                │                 │
│         ▼                ▼                ▼                 │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                  Storage Layer                        │   │
│  │  ┌──────────────────────────────────────────────┐    │   │
│  │  │              SQLite Database                  │    │   │
│  │  │  • memories table (encrypted blobs)          │    │   │
│  │  │  • vector_clocks table (causality tracking)  │    │   │
│  │  │  • sync_metadata table (sync state)          │    │   │
│  │  └──────────────────────────────────────────────┘    │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## Contributing

We welcome contributions! Please follow these steps:

1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Commit** your changes (`git commit -m 'Add amazing feature'`)
4. **Push** to the branch (`git push origin feature/amazing-feature`)
5. **Open** a Pull Request

### Development Setup

```bash
# Clone your fork
git clone https://github.com/your-username/vault-sync.git
cd vault-sync

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

# Run type checker
mypy .
```

### Code Style

- Follow PEP 8
- Use type hints everywhere
- Write docstrings for all public APIs
- Keep functions focused and small

---

## Roadmap

### v1.0 (Current)
- [x] Core VaultStore with encryption
- [x] VectorClock causality tracking
- [x] CRDT sync between devices
- [x] LangChain integration
- [x] Anthropic integration
- [x] 22 passing tests

### v1.1 (Planned)
- [ ] SQLite WAL mode for concurrent access
- [ ] Export/import vault as encrypted JSON
- [ ] Webhook notifications on sync
- [ ] CLI tool for vault management

### v2.0 (Future)
- [ ] Distributed sync via libp2p
- [ ] Zero-knowledge proofs for search
- [ ] Mobile SDKs (iOS/Android)
- [ ] Browser extension for web apps

---

## License

MIT License - see [LICENSE](LICENSE) for details.

---

<p align="center">
  Built with ❤️ for the AI community
</p>
