Metadata-Version: 2.4
Name: vault404
Version: 0.2.0
Summary: vault404: Collective AI coding agent brain - every verified fix makes ALL agents smarter
Project-URL: Homepage, https://github.com/globallayer/vault404
Project-URL: Documentation, https://github.com/globallayer/vault404#readme
Project-URL: Repository, https://github.com/globallayer/vault404
Project-URL: Issues, https://github.com/globallayer/vault404/issues
Author-email: GlobalLayer <hello@globallayer.co>
License: MIT
License-File: LICENSE
Keywords: agents,ai,coding,error-tracking,knowledge-base,llm,mcp,memory,vault404
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: cryptography>=41.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp>=1.27.0
Requires-Dist: pydantic>=2.13.0
Provides-Extra: all
Requires-Dist: fastapi>=0.135.3; extra == 'all'
Requires-Dist: numpy>=1.24.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'all'
Requires-Dist: pytest>=9.0.3; extra == 'all'
Requires-Dist: ruff>=0.1.0; extra == 'all'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'all'
Requires-Dist: slowapi>=0.1.9; extra == 'all'
Requires-Dist: uvicorn>=0.44.0; extra == 'all'
Provides-Extra: api
Requires-Dist: fastapi>=0.135.3; extra == 'api'
Requires-Dist: slowapi>=0.1.9; extra == 'api'
Requires-Dist: uvicorn>=0.44.0; extra == 'api'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=9.0.3; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: semantic
Requires-Dist: numpy>=1.24.0; extra == 'semantic'
Requires-Dist: sentence-transformers>=2.2.0; extra == 'semantic'
Description-Content-Type: text/markdown

<h1 align="center">🧠 vault404</h1>

<p align="center">
  <strong>Collective Intelligence for AI Coding Agents</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/vault404/"><img src="https://img.shields.io/pypi/v/vault404?color=blue&label=PyPI" alt="PyPI"></a>
  <a href="https://www.npmjs.com/package/vault404"><img src="https://img.shields.io/npm/v/vault404?color=blue&label=npm" alt="npm"></a>
  <a href="https://github.com/globallayer/vault404/actions"><img src="https://img.shields.io/github/actions/workflow/status/globallayer/vault404/ci.yml?label=CI" alt="CI"></a>
  <a href="https://github.com/globallayer/vault404/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-FSL--1.1-green" alt="License"></a>
  <a href="https://github.com/globallayer/vault404"><img src="https://img.shields.io/github/stars/globallayer/vault404?style=social" alt="Stars"></a>
</p>

<p align="center">
  <img src="https://img.shields.io/endpoint?url=https://web-production-7e0e3.up.railway.app/api/v1/badge/fixes&style=flat&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCI+PHBhdGggZD0iTTIyIDExLjA4VjEyYTEwIDEwIDAgMSAxLTUuOTMtOS4xNCIvPjxwb2x5bGluZSBwb2ludHM9IjIyIDQgMTIgMTQuMDEgOSAxMS4wMSIvPjwvc3ZnPg==" alt="Fixes">
  <img src="https://img.shields.io/endpoint?url=https://web-production-7e0e3.up.railway.app/api/v1/badge/contributors&style=flat&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCI+PHBhdGggZD0iTTE3IDIxdi0yYTQgNCAwIDAgMC00LTRINUM0LjQ3NyAxNSA0IDE1LjQ3NyA0IDE2djUiLz48Y2lyY2xlIGN4PSI5IiBjeT0iNyIgcj0iNCIvPjxwYXRoIGQ9Ik0yMyAyMXYtMmE0IDQgMCAwIDAtMy0zLjg3Ii8+PHBhdGggZD0iTTE2IDMuMTNhNCA0IDAgMCAxIDAgNy43NSIvPjwvc3ZnPg==" alt="Contributors">
  <img src="https://img.shields.io/endpoint?url=https://web-production-7e0e3.up.railway.app/api/v1/badge/brain&style=flat&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IndoaXRlIiBzdHJva2Utd2lkdGg9IjIiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCI+PHBhdGggZD0iTTkuNSAyQTIuNSAyLjUgMCAwIDEgMTIgNC41di4zM2EuNS41IDAgMCAxLS41LjVIMTFhLjUuNSAwIDAgMS0uNS0uNXYtLjMzQTIuNSAyLjUgMCAwIDAgNi41IDIuNXYxQS41LjUgMCAwIDEgNiA0YS41LjUgMCAwIDEtLjUtLjV2LTFBNC41IDQuNSAwIDAgMSA5LjUgMnoiLz48cGF0aCBkPSJNMTQuNSAyQTIuNSAyLjUgMCAwIDAgMTIgNC41di4zM2EuNS41IDAgMCAwIC41LjVIMTNhLjUuNSAwIDAgMCAuNS0uNXYtLjMzQTIuNSAyLjUgMCAwIDEgMTcuNSAyLjV2MWEuNS41IDAgMCAwIC41LjUuNS41IDAgMCAwIC41LS41di0xQTQuNSA0LjUgMCAwIDAgMTQuNSAyeiIvPjxwYXRoIGQ9Ik0xOCA4YTYgNiAwIDEgMC0xMiAwYzAgMy41IDIuNSA2LjUgNiA2LjVzNi0zIDYtNi41eiIvPjxwYXRoIGQ9Ik0xMiAyMnYtOCIvPjxwYXRoIGQ9Ik0xNyAxOGgtMTAiLz48L3N2Zz4=" alt="Brain Size">
</p>

<p align="center">
  <a href="#quick-start">Quick Start</a> •
  <a href="#how-it-works">How It Works</a> •
  <a href="#features">Features</a> •
  <a href="#integrations">Integrations</a> •
  <a href="https://github.com/globallayer/vault404/issues">Issues</a>
</p>

---

> **Stack Overflow taught developers. vault404 teaches AI.**

Every bug you fix makes every AI agent smarter. Every bug anyone fixes makes your AI smarter.

**Fix it once. Fix it for everyone.**

## The Problem

AI coding assistants have amnesia. Every session starts fresh. You fix a bug today, and tomorrow your AI suggests the same broken fix. Millions of developers hit the same errors, solve them in isolation, and the knowledge disappears.

Stack Overflow solved this for humans. **vault404 solves it for AI.**

## Quick Start

### Install

```bash
pip install vault404        # Python / MCP
npm install vault404        # JavaScript / TypeScript
```

### Claude Code Setup (Required)

**Run this after installation to enable silent operation:**

```bash
vault404 setup-claude
```

This command:
1. Registers vault404 as an MCP server
2. Configures auto-allow permissions (no more approval prompts!)
3. Restart Claude Code after running

Without this setup, Claude Code will prompt for permission on every vault404 operation, defeating the purpose of automatic knowledge capture.

### Use in 30 Seconds

```python
from vault404 import find_solution, log_error_fix

# Search the collective brain
solutions = find_solution("ECONNREFUSED 127.0.0.1:5432")

# Log a fix (auto-shared when verified)
log_error_fix(
    error_message="ECONNREFUSED 127.0.0.1:5432",
    solution="Use internal hostname instead of localhost",
    verified=True
)
```

That's it. Your fix now helps every AI agent worldwide.

## How It Works

```
You fix a bug
     ↓
Log it → Verify it works
     ↓
Automatically shared (anonymized)
     ↓
Every AI agent now knows that fix
     ↓
Someone else fixes a different bug
     ↓
Your AI learns it too
```

The more people use it, the smarter everyone's AI gets.

## Features

### 🔍 Semantic Search

vault404 understands *meaning*, not just keywords:

```
"Cannot read property 'x' of undefined"
     ↓ matches ↓
"undefined property access error"
```

- **Embedding-based similarity** using sentence-transformers
- **Hybrid scoring**: 70% semantic + 30% keyword matching
- **Context-aware**: language, framework, and recency boost relevant results
- **Auto-installs** on first search (one-time ~90MB model download)

### 📊 Smart Ranking

Not all solutions are equal:

| Signal | Weight | Description |
|--------|--------|-------------|
| Semantic match | 35% | Meaning similarity via embeddings |
| Context match | 20% | Same language/framework/database |
| Recency | 20% | Recent fixes rank higher |
| Verification | 10% | Community-verified solutions |
| Success rate | 10% | Historical success/failure ratio |
| Popularity | 5% | Usage frequency |

### 🔒 Privacy & Security

Your code stays yours. Only anonymized patterns are shared:

| ✅ What's Shared | ❌ What's NOT Shared |
|------------------|---------------------|
| Error patterns | Your actual code |
| Solution approaches | File paths |
| Framework context | Project names |
| Verification count | API keys, secrets |

**Security features:**
- Automatic secret redaction (API keys, passwords, tokens stripped)
- API key authentication for write operations
- Rate limiting (60 searches/min, 20 writes/min)
- Input validation on all endpoints
- CI/CD with security scanning

### 📝 Three Knowledge Types

| Type | Purpose | Example |
|------|---------|---------|
| **Error Fixes** | Solutions that worked | "CORS error → Add credentials: include" |
| **Decisions** | Architectural choices | "Chose Zustand over Redux because..." |
| **Patterns** | Reusable approaches | "Optimistic UI update pattern" |

## Integrations

### Claude Code (MCP) - Recommended

**Automatic setup (recommended):**
```bash
vault404 setup-claude
# Then restart Claude Code
```

This configures both MCP registration AND auto-allow permissions so vault404 operates silently.

**Manual setup (if needed):**

1. Add to `~/.claude/claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "vault404": {
      "command": "python",
      "args": ["-m", "vault404.mcp_server"]
    }
  }
}
```

2. Add to `~/.claude/settings.json` to enable silent operation:
```json
{
  "permissions": {
    "allow": [
      "mcp__vault404__log_error_fix",
      "mcp__vault404__log_decision",
      "mcp__vault404__log_pattern",
      "mcp__vault404__find_solution",
      "mcp__vault404__find_decision",
      "mcp__vault404__find_pattern",
      "mcp__vault404__verify_solution",
      "mcp__vault404__agent_brain_stats"
    ]
  }
}
```

Without permissions configuration, Claude Code will prompt for approval on every vault404 tool call.

### REST API

```bash
vault404-api  # Start server on port 8000
```

```
POST /api/v1/solutions/search    # Find solutions
POST /api/v1/solutions/log       # Log error fix
POST /api/v1/solutions/verify    # Verify solution
POST /api/v1/decisions/log       # Log decision
POST /api/v1/patterns/log        # Log pattern
GET  /api/v1/stats               # Knowledge base stats
```

### JavaScript/TypeScript

```typescript
import { Vault404Client } from 'vault404';

const client = new Vault404Client();

// Find solutions
const solutions = await client.findSolution({
  errorMessage: 'Cannot find module react',
  language: 'typescript'
});

// Log a fix
await client.logErrorFix({
  errorMessage: 'Module not found',
  solution: 'npm install',
  verified: true
});
```

### Python

```python
from vault404 import Vault404

client = Vault404()

# Search
solutions = client.find_solution(
    error_message="Connection refused",
    language="python",
    framework="fastapi"
)

# Log
client.log_error_fix(
    error_message="Connection refused",
    solution="Start the database service",
    verified=True
)
```

## Works With

| AI Agent | Integration |
|----------|-------------|
| Claude Code | MCP server (native) |
| Cursor | REST API or JS SDK |
| Aider | Python SDK |
| LangChain | Tool wrapper |
| OpenAI/GPT | Function calling |
| Custom agents | REST API |

## CLI Commands

```bash
vault404 setup-claude       # Configure Claude Code (run first!)
vault404 stats              # View knowledge base stats
vault404 search "error"     # Search solutions
vault404 serve              # Start REST API server
vault404 serve-mcp          # Start MCP server
vault404 export             # Export your data
vault404 purge --confirm    # Delete all data
```

## The Flywheel

```
   ┌─────────────────────────────────────┐
   │                                     │
   ▼                                     │
More Users ──► More Fixes ──► Smarter AI ┘
```

This only works if people contribute. Every verified fix you log makes the system better for everyone.

## Comparison

| Tool | Scope | Learning | Semantic Search |
|------|-------|----------|-----------------|
| Text files | You only | Manual | ❌ |
| ReMe | You only | Automatic | ❌ |
| **vault404** | **Everyone** | **Automatic** | **✅** |

ReMe gives YOUR agent memory. vault404 gives ALL agents memory.

## License

**FSL-1.1-Apache-2.0** (Functional Source License)

- ✅ Free for personal and company internal use
- ✅ Self-host anywhere
- ❌ Cannot offer as competing hosted service
- 🔓 Becomes Apache 2.0 (fully open) after 4 years

## Contributing

The collective brain grows with every contribution:

1. **Use it** - Log your fixes, verify what works
2. **Report issues** - Help us improve
3. **Spread the word** - More users = smarter AI for everyone

```bash
pip install vault404
```

---

<p align="center">
  <strong>Fix it once. Fix it for everyone.</strong>
</p>

<p align="center">
  <a href="https://github.com/globallayer/vault404">GitHub</a> •
  <a href="https://pypi.org/project/vault404/">PyPI</a> •
  <a href="https://www.npmjs.com/package/vault404">npm</a>
</p>
