Metadata-Version: 2.1
Name: rewind-memory
Version: 0.4.3
Summary: Bio-inspired persistent memory for AI agents. 5-layer architecture with FTS5, vector search, knowledge graph, and HybridRAG fusion.
Author-email: SARAI Defence <vova@saraidefence.com>
License: Apache-2.0
Project-URL: Homepage, https://saraidefence.com
Project-URL: Documentation, https://saraidefence.com/docs
Project-URL: Repository, https://github.com/saraidefence/rewind-memory
Keywords: memory,ai,agents,rag,bio-inspired,knowledge-graph
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: dev
Requires-Dist: pytest >=7.0 ; extra == 'dev'
Requires-Dist: ruff >=0.1 ; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: httpx >=0.24 ; extra == 'mcp'
Provides-Extra: proxy
Requires-Dist: uvicorn >=0.27 ; extra == 'proxy'
Provides-Extra: vector
Requires-Dist: sqlite-vec >=0.0.1 ; extra == 'vector'

# 🧠 Rewind Memory

**Bio-inspired persistent memory for AI agents.**

Rewind gives AI agents structured, persistent memory that works like biological memory — keyword search, knowledge graphs, semantic vectors, and score fusion. Runs fully local on SQLite with zero external dependencies.

## Architecture

```
┌─────────────────────────────────────────┐
│            L2 Orchestrator              │
│    (fusion · ranking · deduplication)   │
├─────────┬─────────┬─────────┬──────────┤
│   L0    │   L1    │   L3    │    L4    │
│Sensory  │ System  │  Graph  │  Vector  │
│ Buffer  │  Files  │         │  Search  │
│         │         │         │          │
│ SQLite  │  File   │ SQLite  │sqlite-vec│
│  FTS5   │ system  │  Graph  │ (vec0)   │
└─────────┴─────────┴─────────┴──────────┘
```

## Layers

| Layer | Name | Bio Analogy | Backend | Purpose |
|-------|------|-------------|---------|---------|
| **L0** | Sensory Buffer | Sensory cortex | SQLite FTS5 | Fast keyword search, BM25 ranking |
| **L1** | System Memory | Working memory | File system | Identity, preferences, context — loaded every session |
| **L2** | Orchestrator | Prefrontal cortex | In-process | Fuses keyword + graph + vector results |
| **L3** | Knowledge Graph | Association cortex | SQLite | Entity relationships, spreading activation, Hebbian learning |
| **L4** | Vector Search | Episodic memory | sqlite-vec | Semantic similarity via local embeddings (Ollama) |

## Quick Start

> **Full walkthrough:** [docs/QUICKSTART.md](docs/QUICKSTART.md) — 5 minutes to first search.

```bash
# 1. Install Ollama for vector search (optional but recommended)
curl -fsSL https://ollama.com/install.sh | sh
ollama pull nomic-embed-text  # ~274MB

# 2. Install Rewind
pip install rewind-memory

# 3. Ingest your files
rewind ingest ~/my-project/docs/

# 4. Search
rewind search "what was decided about auth"
```

### Usage

```python
from rewind.client import RewindClient
from rewind.config import default_config

client = RewindClient(default_config("free"))

# Search across all layers
results = client.search("what is Hebbian learning")
for r in results:
    print(f"{r.score:.2f} [{r.layer}] {r.text[:80]}")

# Ingest a document
client.ingest("notes/meeting.md")

# Health check
print(client.health())
```

### CLI

```bash
# Search
rewind search "memory consolidation" --limit 10

# Ingest files
rewind ingest ./documents/

# Health check
rewind health
```

### Integrations (Claude Code, Cursor, OpenClaw)

Rewind ships with an MCP server that works with any MCP-compatible tool:

**Claude Code** — add to `~/.claude/settings.json`:
```json
{
  "mcpServers": {
    "rewind": {
      "command": "rewind-mcp"
    }
  }
}
```

**OpenClaw** — config setup + optional gateway pre-turn hook:
```bash
# Route memory_search through Rewind
rewind-openclaw setup --url http://localhost:8031

# Patch the gateway to auto-inject memory into EVERY inbound message
# (the agent gets memory context before it even starts thinking)
rewind-openclaw patch
```

**Cursor / Windsurf / Cline** — add `rewind-mcp` as an MCP server in settings.

See [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md) for full setup guides.

### Memory Proxy (zero-config, works with any tool)

The proxy auto-injects memory into every LLM call. No MCP needed — just change your API URL:

```bash
pip install rewind-memory[proxy]

# Ingest your project first
rewind ingest ./my-project/

# Start the memory proxy
rewind proxy --port 8080
```

Then point your tool at it:

```bash
# Cursor
OPENAI_BASE_URL=http://localhost:8080/v1 cursor .

# Aider
OPENAI_API_BASE=http://localhost:8080/v1 aider

# Any OpenAI-compatible tool
export OPENAI_BASE_URL=http://localhost:8080/v1
```

The proxy:
- Searches memory on every prompt (keyword + graph + vector fusion)
- Injects relevant context into the system message
- Auto-budgets injection size based on model context limits
- Passes through your API key to the upstream provider
- Supports streaming responses
- Works with OpenAI, Anthropic, NVIDIA, any OpenAI-compatible API

```bash
# Point at Anthropic instead of OpenAI
rewind proxy --port 8080 --upstream https://api.anthropic.com/v1

# Point at a local model
rewind proxy --port 8080 --upstream http://localhost:11434/v1
```

## Configuration

```yaml
# ~/.rewind/config.yaml
tier: free
workspace_path: ~/my-project

embedding:
  provider: ollama
  model: nomic-embed-text
  url: http://localhost:11434

layers:
  l0_sensory: true
  l1_stm: true
  l3_graph: true
  l4_workspace: true
```

## Upgrading

Rewind Core is free and fully functional as a local memory stack. For additional layers (communications, documents, bio lifecycle) and cloud GPU embeddings, see [Rewind Pro](https://saraidefence.com/#pricing).

Pro extends the Core package via a plugin — install both and Pro layers activate automatically:

```python
client = RewindClient(default_config("pro"), api_key="rw_live_...")
```

| Feature | Core (Free) | Pro ($9/mo) | MOS (Custom) |
|---------|-------------|-------------|--------------|
| Keyword search (FTS5) | ✅ | ✅ | ✅ |
| System memory | ✅ | ✅ | ✅ |
| Knowledge graph (SQLite) | ✅ | ✅ | ✅ |
| Semantic vector search | ✅ local Ollama | ✅ cloud GPU (A10G) | ✅ custom GPU |
| HybridRAG fusion | ✅ 5-layer (L0+L1+L3+L4+orchestrator) | full 7-layer | full 7-layer |
| Communications memory (L5) | — | ✅ | ✅ |
| Document store (L6) | — | ✅ | ✅ |
| Cloud GPU embeddings (NV-Embed-v2) | — | 25K/mo included | custom volume rates |
| Retrieval feedback learning | — | ✅ | ✅ |
| Migration assist (→ Neo4j/Qdrant) | — | ✅ | ✅ |
| Bio lifecycle (decay, pruning) | — | — | ✅ |
| Air-gapped deployment | — | — | ✅ |
| Dedicated engineer + SLA | — | — | ✅ |

## Development

```bash
git clone https://github.com/saraidefence/rewind-memory.git
cd rewind-memory
pip install -e ".[dev]"
pytest tests/
```

## Patent

The 7-layer bio-inspired memory architecture is patent pending.

## License

Apache License 2.0 — see [LICENSE](LICENSE).

---

Built by [SARAI Defence](https://saraidefence.com). Ukrainian-built. Patent pending.
