# MouseBase

> MouseBase is persistent memory infrastructure for AI applications and agents. It provides APIs and storage/retrieval primitives for giving AI systems long-term memory, backed by PostgreSQL with pgvector and full-text search.

## What MouseBase Does

AI agents and chatbots lose context between sessions. MouseBase solves this by providing a hosted memory API where applications can store, search, update, and delete memories. Memories are retrieved using hybrid search — combining semantic (vector embedding), keyword (full-text), metadata, and recency signals.

MouseBase is not a vector database. It is a complete memory infrastructure layer with authentication, project scoping, API key management, plan enforcement, SDKs, and a developer dashboard.

## Key URLs

- Website: https://mousebase.dev
- API: https://api.mousebase.dev/api/v1
- Dashboard: https://mousebase.dev
- Python SDK: https://pypi.org/project/mousebase/ (15 releases, v0.3.2)
- JavaScript SDK: https://www.npmjs.com/package/mousebase (370+ monthly downloads)
- GitHub: https://github.com/Lumine8/MouseBase-AI
- Documentation: https://mousebase.dev/docs

## SDKs

### Python
```bash
pip install mousebase
```
```python
from mousebase import MouseBase
client = MouseBase(api_key="mb_live_...")
client.remember("User prefers dark mode", metadata={"category": "preferences"})
results = client.search("What theme does the user want?", top_k=5)
```

### JavaScript / TypeScript
```bash
npm install mousebase
```
```typescript
import { MouseBase } from "mousebase";
const client = new MouseBase({ apiKey: process.env.MOUSEBASE_API_KEY! });
await client.remember({ content: "User prefers dark mode" });
const results = await client.search({ query: "UI preferences", top_k: 5 });
```

## API Endpoints

Base URL: https://api.mousebase.dev/api/v1

### Memory
- POST /remember/ — Store a memory
- POST /search/ — Hybrid search (semantic + keyword + metadata + recency)
- GET /memory/{id} — Get a memory
- PATCH /memory/{id} — Update a memory
- DELETE /memory/{id} — Delete a memory
- GET /memories/ — List memories with pagination and filters

### Authentication
- POST /auth/signup — Create account
- POST /auth/login — Sign in (returns JWT access + refresh tokens)
- POST /auth/refresh — Refresh access token
- POST /auth/logout — Revoke refresh token
- POST /auth/forgot-password — Request password reset
- POST /auth/reset-password — Reset password with token

### Projects
- GET /projects/ — List projects
- POST /projects/ — Create project
- GET /projects/{id} — Get project
- PATCH /projects/{id} — Update project
- DELETE /projects/{id} — Delete project
- POST /projects/{id}/rotate-key — Rotate API key

### Usage & Analytics
- GET /dashboard/metrics — Dashboard metrics
- GET /dashboard/analytics — Usage analytics
- GET /stats/downloads — SDK download stats

### Billing
- POST /payments/create-order — Create Razorpay order
- POST /payments/verify — Verify payment
- GET /payments/invoice/{id} — Get invoice

## Pricing

| Plan | Price | Memories | Projects | Searches/mo |
|------|-------|----------|----------|-------------|
| Free | $0/mo | 5,000 | 3 | 5,000 |
| Hobby | $3.99/mo | 25,000 | 5 | 25,000 |
| Pro | $7.99/mo | 250,000 | 10 | 250,000 |

## Architecture

- Frontend: React SPA on Vercel
- API: FastAPI + uvicorn on Render
- Database: PostgreSQL 18 with pgvector on Neon
- Embeddings: Gemini or OpenAI (configurable per project)
- Search: Hybrid — pgvector cosine distance + PostgreSQL tsvector/tsquery + metadata + recency
- Payments: Razorpay
- Monitoring: Sentry, GitHub Actions uptime checks
- Backups: Daily pg_dump with weekly restore verification

## Contact

- Email: support@mousebase.dev
- GitHub Issues: https://github.com/Lumine8/MouseBase-AI/issues