Metadata-Version: 2.1
Name: rewind-memory
Version: 0.4.2
Summary: 7-layer bio-inspired memory architecture for AI agents
Author-email: SARAI Defence <vova@saraidefence.com>
License: Apache-2.0
Keywords: memory,ai,agents,rag,bio-inspired
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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 :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml >=6.0
Requires-Dist: httpx >=0.24
Provides-Extra: all
Requires-Dist: rewind-memory[api,comms,docs,graph,mcp,vector] ; extra == 'all'
Provides-Extra: api
Requires-Dist: fastapi >=0.100 ; extra == 'api'
Requires-Dist: uvicorn >=0.20 ; extra == 'api'
Requires-Dist: pydantic >=2.0 ; extra == 'api'
Requires-Dist: stripe >=7.0 ; extra == 'api'
Provides-Extra: comms
Requires-Dist: qdrant-client >=1.7 ; extra == 'comms'
Provides-Extra: dev
Requires-Dist: pytest >=7.0 ; extra == 'dev'
Requires-Dist: pytest-asyncio >=0.21 ; extra == 'dev'
Requires-Dist: ruff >=0.1 ; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sentence-transformers >=2.0 ; extra == 'docs'
Provides-Extra: graph
Requires-Dist: neo4j >=5.0 ; extra == 'graph'
Provides-Extra: mcp
Requires-Dist: httpx >=0.24 ; extra == 'mcp'
Provides-Extra: vector
Requires-Dist: sqlite-vec >=0.0.1 ; extra == 'vector'

# Rewind Memory

**Persistent, bio-inspired memory for AI agents — local-first, production-ready.**

- Remembers everything across Claude Code sessions: conversations, files, decisions, relationships
- 5-layer architecture modelled on biological memory (sensory → STM → knowledge graph → workspace)
- Ships as a Claude Code plugin — one command to set up, zero config to start
- Runs entirely offline; Pro tier adds L5/L6 layers, cloud embeddings, and graph intelligence

---

## Architecture

```
┌──────────────────────────────────────────┐
│              L2  Orchestrator             │
│    fusion · ranking · entity extraction   │
├──────────┬─────────┬─────────┬───────────┤
│    L0    │   L1    │   L3    │    L4     │
│ Sensory  │  STM    │  Graph  │ Workspace │
│  Buffer  │(Vector) │         │  (Files)  │
│FTS5/BM25 │sqlite-  │ SQLite /│ sqlite-   │
│          │  vec    │  Neo4j  │   vec     │
└──────────┴─────────┴─────────┴───────────┘

Pro adds: L5 Communications (Qdrant) · L6 Documents (Qdrant + FTS5)
```

| Layer | Name | Bio analogue | Default backend |
|-------|------|--------------|-----------------|
| L0 | Sensory Buffer | Sensory cortex | SQLite FTS5 + BM25 |
| L1 | Short-Term Memory | Hippocampus | sqlite-vec |
| L2 | Orchestrator | Prefrontal cortex | In-process |
| L3 | Graph Memory | Association cortex | SQLite / Neo4j |
| L4 | Workspace | Working memory | sqlite-vec |

---

## Quick Start

```bash
pip install rewind-memory
```

Then, inside Claude Code:

```
/rewind-setup
```

That's it. The command detects your environment, picks the best available
configuration, and writes `~/.rewind/config.yaml`.

---

## Tiers

| Feature | Free | Pro ($18/mo — $9 for early adopters) | Enterprise |
|---------|------|-------------|------------|
| Embedding model | all-MiniLM-L6-v2 (768-dim, local) | NV-Embed-v2 (4096-dim, Modal cloud) | Custom |
| KG extraction | Heuristic (regex) or Ollama local | Graph-PReFLexOR on Modal T4 | Custom LLM |
| Reranking | None | Cross-encoder on Modal T4 | Custom |
| Batch extraction | No | Yes | Yes |
| Storage | Local SQLite | Local SQLite + Qdrant + Neo4j | Managed |
| API server | Self-hosted | Self-hosted + cloud relay | Managed |
| Support | Community | Email | SLA |

---

## Claude Code Plugin Setup

### Install

```bash
pip install rewind-memory
git clone https://github.com/saraidefence/rewind-memory.git ~/.claude-plugins/rewind-memory
```

### Activate

```bash
claude --plugin-dir ~/.claude-plugins/rewind-memory/plugin
```

### Initialise

```
/rewind-setup
```

### Available commands

| Command | Description |
|---------|-------------|
| `/rewind-setup` | Detect environment and write config |
| `/remember <text>` | Store a note in memory |
| `/recall <query>` | Search all memory layers |
| `/rewind-status` | Show active layers and stats |

---

## Pro Setup

### 1. Subscribe

Visit [rewind.sh/pro](https://rewind.sh/pro) or run:

```bash
rewind upgrade
```

This opens a Stripe Checkout page. Complete payment with any card.

### 2. Get your API key

After payment, the confirmation page displays your key:

```
rwnd_live_<32 hex chars>
```

**Copy it immediately** — for security it is not stored in plaintext after this page.

### 3. Configure

Add the key to `~/.rewind/config.yaml`:

```yaml
tier: pro
modal:
  auth_token: rwnd_live_<your-key>
embedding:
  provider: modal
  model: nvidia/NV-Embed-v2
  dim: 4096
kg:
  provider: modal
  model: graph-preflexor
```

Or set it with the CLI:

```bash
rewind config set tier pro
rewind config set modal.auth_token rwnd_live_<your-key>
```

### 4. Re-embed (if upgrading from Free)

If you have existing data from the free tier, re-embed your chunks through
NV-Embed-v2 for 4096-dim vectors:

```bash
rewind migrate --reindex
```

This reads your token from `config.yaml`. Progress is shown per batch.

### 5. Verify

```bash
rewind health
```

### Manage your subscription

```
GET /portal?customer_id=<stripe-customer-id>
```

Or visit your Stripe customer portal directly at [rewind.sh/portal](https://rewind.sh/portal).

---

## Configuration Reference

Full path: `~/.rewind/config.yaml`

```yaml
# Tier: free | pro | enterprise
tier: free

# Data storage root
data_dir: ~/.rewind/data

embedding:
  provider: local          # local | modal
  model: all-MiniLM-L6-v2  # or nvidia/NV-Embed-v2 for Pro
  dim: 768                 # 768 (free) | 4096 (pro)

kg:
  provider: heuristic      # heuristic | ollama | modal
  model: null              # e.g. saraidefence/graph-preflexor:latest

modal:
  auth_token: null         # rwnd_live_<key> — Pro/Enterprise only

# Optional: Neo4j backend for L3 (enterprise)
neo4j:
  uri: bolt://localhost:7687
  user: neo4j
  password: null
```

Config files for each tier live in `configs/`:

| File | Purpose |
|------|---------|
| `configs/free.yaml` | Default free tier |
| `configs/pro.yaml` | Pro cloud settings |
| `configs/enterprise.yaml` | Enterprise / self-managed |

---

## API Reference (CLI)

```
rewind init                    Initialise data directory
rewind health                  Check layer status
rewind ingest <path>           Index files into memory
rewind search <query>          Search across all layers
rewind recall <query>          Alias for search
rewind remember <text>         Store a manual note
rewind config get <key>        Read a config value
rewind config set <key> <val>  Write a config value
rewind upgrade                 Open Pro checkout
rewind migrate --reindex       Re-embed all chunks (768→4096 for Pro)
rewind export                  Export memory to JSON
```

---

## Self-Hosted (Docker)

```bash
git clone https://github.com/saraidefence/rewind-memory.git
cd rewind-memory
docker compose -f docker/docker-compose.yml up -d
```

The API server starts on `http://localhost:8080`.

Environment variables for the Stripe integration:

```env
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRO_PRICE_ID=price_...
REWIND_BASE_URL=https://your-domain.com
REWIND_DATA_DIR=/data
```

Register the webhook endpoint in your Stripe dashboard:

```
POST https://your-domain.com/stripe/webhook
```

Events to enable:
- `checkout.session.completed`
- `customer.subscription.deleted`
- `invoice.payment_succeeded`

---

## Development

```bash
git clone https://github.com/saraidefence/rewind-memory.git
cd rewind-memory
pip install -e ".[api,graph,vector,comms,docs]"
pip install stripe
pytest
```

---

## Licence

MIT — see [LICENSE](LICENSE).

---

*Built by [SARAI Defence](https://github.com/saraidefence). Not affiliated with Anthropic.*
