Metadata-Version: 2.4
Name: surreal-memory
Version: 2.1.0
Summary: Reflex-based memory system for AI agents with SurrealDB backend — retrieval through activation, not search
Project-URL: Homepage, https://github.com/acidkill/surreal-memory
Project-URL: Documentation, https://github.com/acidkill/surreal-memory/blob/main/docs/getting-started/quickstart.md
Project-URL: Repository, https://github.com/acidkill/surreal-memory
Project-URL: Issues, https://github.com/acidkill/surreal-memory/issues
Author: Surreal-Memory Contributors (upstream)
Author-email: Toni Nowak <t.nowak@ai-flow.no>
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE
Keywords: agents,ai,graph,llm,memory,neural,retrieval
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: networkx>=3.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer<0.26,>=0.9.0
Requires-Dist: typing-extensions>=4.0
Provides-Extra: all
Requires-Dist: chromadb>=0.4.0; extra == 'all'
Requires-Dist: fastapi>=0.100; extra == 'all'
Requires-Dist: google-genai>=1.0; extra == 'all'
Requires-Dist: httpx>=0.24; extra == 'all'
Requires-Dist: mem0ai>=0.1.0; extra == 'all'
Requires-Dist: python-multipart>=0.0.22; extra == 'all'
Requires-Dist: pyvi>=0.1; extra == 'all'
Requires-Dist: spacy>=3.6; extra == 'all'
Requires-Dist: surrealdb>=0.4.0; extra == 'all'
Requires-Dist: underthesea>=6.0; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.23; extra == 'all'
Provides-Extra: chromadb
Requires-Dist: chromadb>=0.4.0; extra == 'chromadb'
Provides-Extra: cognee
Requires-Dist: cognee>=0.1.0; extra == 'cognee'
Provides-Extra: dev
Requires-Dist: click>=8.0; extra == 'dev'
Requires-Dist: httpx>=0.24; extra == 'dev'
Requires-Dist: mypy>=1.5; extra == 'dev'
Requires-Dist: pre-commit>=3.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.2; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mike>=2.0; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.0; extra == 'embeddings'
Provides-Extra: embeddings-gemini
Requires-Dist: google-genai>=1.0; extra == 'embeddings-gemini'
Provides-Extra: embeddings-openai
Requires-Dist: openai>=1.0; extra == 'embeddings-openai'
Provides-Extra: embeddings-openrouter
Requires-Dist: openai>=1.0; extra == 'embeddings-openrouter'
Provides-Extra: encryption
Requires-Dist: cryptography>=46.0.5; extra == 'encryption'
Provides-Extra: extract
Requires-Dist: beautifulsoup4>=4.12; extra == 'extract'
Requires-Dist: markdownify>=0.11; extra == 'extract'
Requires-Dist: openpyxl>=3.1; extra == 'extract'
Requires-Dist: pymupdf4llm>=0.0.10; extra == 'extract'
Requires-Dist: python-docx>=1.0; extra == 'extract'
Requires-Dist: python-pptx>=0.6.23; extra == 'extract'
Provides-Extra: graphiti
Requires-Dist: graphiti-core>=0.1.0; extra == 'graphiti'
Provides-Extra: integration
Requires-Dist: chromadb>=0.4.0; extra == 'integration'
Requires-Dist: mem0ai>=0.1.0; extra == 'integration'
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.10.0; extra == 'llamaindex'
Provides-Extra: mem0
Requires-Dist: mem0ai>=0.1.0; extra == 'mem0'
Provides-Extra: nlp
Requires-Dist: pyvi>=0.1; extra == 'nlp'
Requires-Dist: spacy>=3.6; extra == 'nlp'
Requires-Dist: underthesea>=6.0; extra == 'nlp'
Provides-Extra: nlp-en
Requires-Dist: spacy>=3.6; extra == 'nlp-en'
Provides-Extra: nlp-vi
Requires-Dist: pyvi>=0.1; extra == 'nlp-vi'
Requires-Dist: underthesea>=6.0; extra == 'nlp-vi'
Provides-Extra: reranker
Requires-Dist: sentence-transformers>=2.2.0; extra == 'reranker'
Provides-Extra: server
Requires-Dist: fastapi>=0.100; extra == 'server'
Requires-Dist: httpx>=0.24; extra == 'server'
Requires-Dist: python-multipart>=0.0.22; extra == 'server'
Requires-Dist: uvicorn[standard]>=0.23; extra == 'server'
Provides-Extra: surrealdb
Requires-Dist: surrealdb>=0.4.0; extra == 'surrealdb'
Provides-Extra: watch
Requires-Dist: watchdog>=4.0.0; extra == 'watch'
Description-Content-Type: text/markdown

# Surreal-Memory

[![PyPI](https://img.shields.io/pypi/v/surreal-memory.svg)](https://pypi.org/project/surreal-memory/)
[![CI](https://github.com/acidkill/surreal-memory/workflows/CI/badge.svg)](https://github.com/acidkill/surreal-memory/actions)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![SurrealDB](https://img.shields.io/badge/Powered_by-SurrealDB-ff00e5)](https://surrealdb.com/)

**Persistent graph memory for AI agents, powered by SurrealDB.**

All features are free and open source. No license keys. No paywalls. No embedding API required for basic usage.

```bash
pip install surreal-memory[surrealdb]
smem init --full
```

Restart your AI tool. Your agent now remembers.

---

## Why Surreal-Memory?

Most AI memory tools are vector databases with a search API bolted on. Surreal-Memory is a **graph that thinks** — memories are stored as interconnected neurons and recalled through spreading activation, backed by SurrealDB's multi-model engine (document + graph + vector in one database).

```
Query: "Why did Tuesday's outage happen?"

Surreal-Memory traces the chain:
outage ← CAUSED_BY ← JWT expiry ← SUGGESTED_BY ← Alice's review
```

**Relationships are explicit** — `CAUSED_BY`, `LEADS_TO`, `RESOLVED_BY`, `CONTRADICTS` — so your agent doesn't just find memories, it *reasons* through them.

| | RAG / Vector Search | Surreal-Memory |
|--|---------------------|----------------|
| Backend | Pinecone / Chroma | **SurrealDB** (doc + graph + vector) |
| Retrieval | Similarity score | Graph traversal + vector search |
| Relationships | None | 41 explicit synapse types |
| LLM required | Yes (embeddings) | No — works fully offline |
| Multi-hop reasoning | Multiple queries | One traversal |
| Memory lifecycle | Static | Decay, reinforcement, consolidation |
| Cost per 1K queries | ~$0.02 | **$0.00** |

---

## What's Different From NeuralMemory?

Surreal-Memory builds on [NeuralMemory](https://github.com/nhadaututtheky/neural-memory)'s graph memory architecture but replaces the SQLite + paid-Pro model with **SurrealDB + free community plugin**:

| | NeuralMemory (upstream) | Surreal-Memory |
|--|---------------|----------------|
| Storage engine | SQLite (limited) | **SurrealDB** (all features free) |
| Vector search | Paid Pro feature | **Built-in** via SurrealDB HNSW |
| Semantic recall | Paid Pro feature | **Free** via community plugin |
| Smart consolidation | Paid Pro feature | **Free** via community plugin |
| Compression | Paid Pro feature | **Free** via community plugin |
| License required | Yes for Pro features | **No** — everything is free |
| Multi-model | No | **Yes** — document + graph + vector |

---

## Quick Start

### Automated Setup (Claude Code)

Give this to Claude Code on any machine and it handles everything — prerequisites, Docker, MCP registration, and verification:

```
Please read INSTALL_PROMPT.md and follow the instructions to set up Surreal-Memory on this machine.
```

Or clone and point Claude Code at the file:

```bash
git clone https://github.com/acidkill/surreal-memory.git
# then in Claude Code:
# "Read INSTALL_PROMPT.md and follow the setup instructions"
```

### Docker (manual)

```bash
cp .env.example .env    # edit with your keys
docker compose -f docker-compose.surrealdb.yml up -d
```

Dashboard at http://localhost:8000/ui, SurrealDB at localhost:8001.

### Manual

```bash
pip install surreal-memory[surrealdb]
smem init --full
```

### First Memory

```bash
smem remember "Fixed auth bug with null check in login.py:42"
smem recall "auth bug"
# → "Fixed auth bug with null check in login.py:42"
```

---

## 3 Tools. That's It.

53 MCP tools are available, but you only need three:

| Tool | What it does |
|------|-------------|
| `smem_remember` | Store a memory — auto-detects type, tags, and connections |
| `smem_recall` | Recall through spreading activation + vector search |
| `smem_health` | Brain health score (A–F) with actionable fix suggestions |

Everything else — sessions, context loading, habit tracking, maintenance — works transparently in the background.

---

## Architecture

```
                    ┌──────────────────────────────┐
                    │       MCP Server (53 tools)   │
                    └──────────┬───────────────────┘
                               │
                    ┌──────────▼───────────────────┐
                    │     Engine (encoding +        │
                    │     retrieval pipeline)       │
                    └──────────┬───────────────────┘
                               │
              ┌────────────────▼────────────────┐
              │        SurrealDB Backend         │
              │  ┌─────────┬─────────┬────────┐ │
              │  │ Document │  Graph  │ Vector │ │
              │  │  Store   │ Queries │  HNSW  │ │
              │  └─────────┴─────────┴────────┘ │
              └─────────────────────────────────┘
```

### Core Data Model

- **Brain** — top-level container with configuration
- **Neuron** — atomic knowledge node (entity, concept, time, action, intent, state)
- **Synapse** — typed, directed edge between neurons (41 types: `CAUSED_BY`, `LEADS_TO`, etc.)
- **Fiber** — a memory record: typed content with metadata, priority, tags, lifecycle stage

### Engine

- **Encoding Pipeline** — composable async steps: extract entities → create neurons → link synapses → bundle into fibers
- **Reflex Retrieval** — spreading activation through the neuron graph, combined with SurrealDB vector search when available
- **Consolidation** — merges similar neurons, reinforces strong paths, prunes weak ones
- **Compression** — 5-tier lifecycle: full → summary → essence → ghost → metadata

### Community Plugin

The built-in `CommunityPlugin` provides all Pro-tier features at no cost:

- **Cone Queries** — HNSW vector search via SurrealDB for semantic recall
- **Smart Merge** — embedding-based neuron consolidation
- **Directional Compression** — multi-axis semantic preservation
- **SurrealDB Storage Backend** — registered automatically when `[surrealdb]` extra is installed

---

## Cloud Sync

Sync your brain across every machine through your own Cloudflare Worker:

```
Laptop ←→ Your Cloudflare Worker ←→ Desktop
                  ↕
              Your Phone
```

You deploy the sync hub to **your own Cloudflare account**. Your D1 database, your encryption key, your data.

```bash
smem sync --full    # bi-directional sync
smem sync --auto    # auto-sync after every remember/recall
```

Sync uses **Merkle delta** — only diffs travel, not the full brain.

---

## Features

#### Memory & Recall
- **15 memory types** — fact, decision, error, insight, preference, workflow, instruction, and more
- **Spreading activation** — memories surface by association, not keyword match
- **Vector search** — SurrealDB HNSW for semantic similarity (when embeddings are configured)
- **Cognitive reasoning** — hypothesize, submit evidence, make predictions, verify with Bayesian confidence

#### Knowledge Ingestion
- **Train from documents** — PDF, DOCX, PPTX, HTML, JSON, XLSX, CSV ingested into permanent brain knowledge
- **Train from database schemas** — extract table structures and FK relationships
- **Import adapters** — migrate from ChromaDB, Mem0, Cognee, Graphiti, LlamaIndex

#### Lifecycle & Storage
- **Memory consolidation** — episodic memories mature into semantic knowledge
- **Compression tiers** — full → summary → essence → ghost → metadata
- **Brain versioning** — snapshot, rollback, diff, transplant memories between brains

#### Ecosystem
- **Web dashboard** — 7-page React UI with graph visualization, health radar, timeline
- **VS Code extension** — memory tree, graph explorer, CodeLens, WebSocket sync
- **Safety** — Fernet encryption, sensitive content auto-detection, input firewall
- **Plugin system** — extend with custom retrieval strategies, compression, and storage backends

---

## Embeddings

The keyword + graph core works with **no embedding API at all**. Embeddings are
optional — they add semantic recall (vector search via SurrealDB HNSW) so memories
surface even when the wording differs. Configure interactively with `smem setup embeddings`
or via `SURREAL_MEMORY_EMBEDDING_*` env vars.

**Recommended — Google Gemini** (`gemini-embedding-001`, 3072-dim, multilingual, free tier):

```bash
pip install "surreal-memory[surrealdb,embeddings-gemini]"
export GEMINI_API_KEY=...        # free key: https://aistudio.google.com/apikey
```

**No API key? Run it locally** — the same on-device model class ChromaDB/MemPalace use,
via `sentence-transformers` (offline, no key):

```bash
pip install "surreal-memory[surrealdb,embeddings]"
smem setup embeddings            # choose "Sentence Transformers"
```

| Provider | Default model | Key | Notes |
|----------|---------------|-----|-------|
| **Gemini** (recommended) | `gemini-embedding-001` | `GEMINI_API_KEY` | 3072-dim, multilingual, free tier |
| Local (sentence-transformers) | `all-MiniLM-L6-v2` · `paraphrase-multilingual-MiniLM-L12-v2` | — | offline, no key, ~440MB download |
| Ollama | `nomic-embed-text` · `bge-m3` | — | local server (`ollama serve`) |
| OpenAI | `text-embedding-3-small` | `OPENAI_API_KEY` | paid |
| OpenRouter | `openai/text-embedding-3-small` | `OPENROUTER_API_KEY` | OpenAI-compatible |

Set the provider to `auto` to pick the best available option at runtime
(order: Ollama → local sentence-transformers → Gemini → OpenAI → OpenRouter).

> Embeddings use **one** model per brain — switching models changes vector
> dimensions and invalidates existing vectors. Pick a provider before ingesting at scale.

---

## Setup by Tool

<details>
<summary><b>Claude Code (Plugin)</b></summary>

```bash
/plugin marketplace add acidkill/surreal-memory
/plugin install surreal-memory@surreal-memory-marketplace
```

</details>

<details>
<summary><b>Cursor / Windsurf / Other MCP Clients</b></summary>

```bash
pip install surreal-memory[surrealdb]
```

Add to your editor's MCP config:

```json
{
  "mcpServers": {
    "surreal-memory": { "command": "smem-mcp" }
  }
}
```

</details>

<details>
<summary><b>OpenClaw (Plugin)</b></summary>

```bash
pip install surreal-memory[surrealdb] && npm install -g surrealmemory
```

Set memory slot in `~/.openclaw/openclaw.json`:
```json
{ "plugins": { "slots": { "memory": "surrealmemory" } } }
```

</details>

<details>
<summary><b>TypeScript / JavaScript (REST SDK)</b></summary>

```bash
npm install @acidkill/surreal-memory-client
```

```ts
import { SurrealMemoryClient } from "@acidkill/surreal-memory-client"

const client = new SurrealMemoryClient({
  baseUrl: "http://localhost:8000",
  brain: "myproject",
})

await client.remember({ content: "Fixed auth bug", type: "fix", priority: 7 })
const { results } = await client.recall({ query: "auth bug" })
```

Full reference: [`integrations/surreal-memory-client/README.md`](integrations/surreal-memory-client/README.md).

</details>

<details>
<summary><b>Docker (self-hosted)</b></summary>

```bash
cp .env.example .env          # configure SurrealDB + embeddings
docker compose -f docker-compose.surrealdb.yml up -d
```

Dashboard: http://localhost:8000/ui

</details>

---

## Python API

```python
import asyncio
from surreal_memory import Brain
from surreal_memory.storage import create_storage
from surreal_memory.core.brain_mode import BrainModeConfig, BrainMode
from surreal_memory.engine.encoder import MemoryEncoder
from surreal_memory.engine.retrieval import ReflexPipeline

async def main():
    config = BrainModeConfig(mode=BrainMode.LOCAL)
    storage = await create_storage(config, brain_id="my_brain")

    encoder = MemoryEncoder(storage, brain.config)
    await encoder.encode("Met Alice to discuss API design")
    await encoder.encode("Decided to use FastAPI for backend")

    pipeline = ReflexPipeline(storage, brain.config)
    result = await pipeline.query("What did we decide about backend?")
    print(result.context)  # "Decided to use FastAPI for backend"

asyncio.run(main())
```

---

## Development

```bash
git clone https://github.com/acidkill/surreal-memory
cd surreal-memory && pip install -e ".[dev]"
smem doctor --dev        # Verify contributor setup
pytest tests/ -v          # 5500+ tests
ruff check src/ tests/    # Lint
make verify               # Full CI gate
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Acknowledgments

Surreal-Memory is built on top of [**NeuralMemory**](https://github.com/nhadaututtheky/neural-memory) by [nhadaututtheky](https://github.com/nhadaututtheky) — an exceptional graph-based memory system for AI agents. The core architecture (neurons, synapses, fibers, spreading activation, consolidation, compression, and the 53-tool MCP interface) is entirely their work.

Surreal-Memory extends it with a SurrealDB storage backend and a community plugin that makes all advanced features available for free.

Equally important: this project would not exist without [**SurrealDB**](https://surrealdb.com/). The combined document + graph + vector model in a single engine is what made it possible to retire the SQLite + paid-Pro split. The shift specifically depends on the changes shipped in **SurrealDB 3.0** — without them, the storage backend in this fork would still be vaporware.

> If you find Surreal-Memory useful, please also star both the [original NeuralMemory project](https://github.com/nhadaututtheky/neural-memory) and [SurrealDB](https://github.com/surrealdb/surrealdb).

## Roadmap

Items here are explicitly **not** in the current release. Community PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md).

### Deferred (external action required)

- **ClawHub listing** — the OpenClaw plugin still needs its ClawHub registry entry aligned to the `surreal-memory` slug. The publish workflow already targets `--slug surreal-memory`; waiting on the registry side.
- **VS Code Marketplace publisher** — `vscode-extension/package.json` now uses publisher `ai-flow-nowak`. The publisher account needs to be created / verified before the next release can push to Marketplace.
- **PyPI canonical name** — `surreal-memory` is the only published package. If any earlier-named package remains on PyPI under an account we control, flag it `Development Status :: 7 - Inactive` with a README pointing at `surreal-memory`.

### Nice-to-haves (community contributions welcome)

- **PostCompact context restore hook** — analog to `session_start.py` but fired right after a Claude Code compaction. Pipes `smem recap` + `smem context --limit 20` to stdout as a `## Context restored after compaction` block, so the agent doesn't lose the thread when the 80% buffer kicks in.
- **PostToolUse memory auto-capture** — observer hook that records memorable patterns (errors solved, decisions made, repeated commands) after Bash / Edit / Write tool calls — no explicit `smem remember` required.
- **JetBrains IDE plugin** — Kotlin / Java plugin using the same REST API as the dashboard. Parity feature for IntelliJ-family IDEs.
- **Cross-device sync UI** — visualize Merkle delta progress, device roster, conflict resolution flow in the dashboard.
- **Cloudflare Pages for docs** — alternative to the removed GitHub Pages workflow. Static `mkdocs build` deployed to CF Pages, no GitHub dependency.
- **LangChain / LlamaIndex retriever adapter** — `from surreal_memory.adapters.langchain import SurrealMemoryRetriever`. Opens the project to the RAG ecosystem.
- **More embedding providers** — Voyage AI, Cohere, Mistral. Current set: Gemini, OpenAI, OpenRouter, local.
- **Upstream sync bot** — scheduled workflow that scans `nhadaututtheky/neural-memory` for new commits, classifies them GREEN / YELLOW / RED against our fork, and opens a draft PR for the green batch.
- **Two-way Telegram bot** — `notify-telegram.yml` is one-way (release notes). Extend with `smem remember` via bot commands.
- **Public benchmarks dashboard** — `benchmarks/` already has stress scripts; publish results as a static dashboard.
- **Brain templates / starter packs** — pre-seeded brains for common workflows (Python dev, K8s admin, research notes).
- **Auto-upgrade path for `~/.neuralmemory/` → `~/.surrealmemory/`** — one-shot migration command for users coming from upstream NeuralMemory.

## License

MIT — see [LICENSE](LICENSE).
