Metadata-Version: 2.4
Name: agentforge-memory-surrealdb
Version: 0.2.3
Summary: SurrealDB-backed MemoryStore, VectorStore, and GraphStore for AgentForge
Project-URL: Homepage, https://github.com/Scaffoldic/agentforge-py
Project-URL: Repository, https://github.com/Scaffoldic/agentforge-py
Project-URL: Documentation, https://github.com/Scaffoldic/agentforge-py
Project-URL: Changelog, https://github.com/Scaffoldic/agentforge-py/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Scaffoldic/agentforge-py/issues
Author: The AgentForge Authors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,graph,memory,rag,surrealdb,surrealql,vector
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: agentforge-core~=0.2.3
Requires-Dist: surrealdb>=1.0
Description-Content-Type: text/markdown

# agentforge-memory-surrealdb

SurrealDB-backed `MemoryStore`, `VectorStore`, and `GraphStore` for the
AgentForge framework.

## What this is

SurrealDB is uniquely multi-modal: a single store supports documents,
graphs, and vectors. This package implements all three locked
contracts against one SurrealDB connection:

- **`SurrealMemoryStore`** — claim audit log
- **`SurrealVectorStore`** — semantic search (HNSW index)
- **`SurrealGraphStore`** — knowledge graph traversal via
  `RELATE` / `->edge->` SurrealQL syntax

All three pass the locked
`agentforge_core.testing.run_*_conformance` suites.

## Usage

```python
from agentforge_memory_surrealdb import (
    SurrealGraphStore,
    SurrealMemoryStore,
    SurrealVectorStore,
)

async with SurrealGraphStore.from_url(
    "ws://localhost:8000/rpc",
    namespace="agentforge",
    database="dev",
    auth=("root", "root"),
) as store:
    await store.add_node(GraphNode(id="paper:1", labels=("Doc",)))
    ...
```

## Local development

```bash
docker compose -f docker-compose.dev.yml up -d
RUN_LIVE_SURREAL=1 SURREAL_URL=ws://localhost:8000/rpc \
  uv run pytest packages/agentforge-memory-surrealdb/tests/integration -v
```

## Capabilities

- **Graph**: `{"transactions", "surrealql", "vector", "live_query"}`
- **Vector**: `{"native_ann"}` (when `init_schema()` provisions the
  HNSW index)
- **Memory**: `{"transactions"}`
