surreal-memory 2.3.2__tar.gz → 2.4.0__tar.gz

{surreal_memory-2.3.2 → surreal_memory-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: surreal-memory
-Version: 2.3.2
+Version: 2.4.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
@@ -38,7 +38,7 @@ 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: surrealdb<3.0.0,>=2.0.0; extra == 'all'
 Requires-Dist: underthesea>=6.0; extra == 'all'
 Requires-Dist: uvicorn[standard]>=0.23; extra == 'all'
 Provides-Extra: chromadb
@@ -104,7 +104,7 @@ 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'
+Requires-Dist: surrealdb<3.0.0,>=2.0.0; extra == 'surrealdb'
 Provides-Extra: watch
 Requires-Dist: watchdog>=4.0.0; extra == 'watch'
 Description-Content-Type: text/markdown

{surreal_memory-2.3.2 → surreal_memory-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "surreal-memory"
-version = "2.3.2"
+version = "2.4.0"
 description = "Reflex-based memory system for AI agents with SurrealDB backend — retrieval through activation, not search"
 readme = "README.md"
 license = "MIT"
@@ -52,7 +52,7 @@ server = [
     "httpx>=0.24",
 ]
 surrealdb = [
-    "surrealdb>=0.4.0",
+    "surrealdb>=2.0.0,<3.0.0",
 ]
 encryption = [
     "cryptography>=46.0.5",

{surreal_memory-2.3.2 → surreal_memory-2.4.0}/src/surreal_memory/__init__.py

@@ -16,7 +16,7 @@ from surreal_memory.engine.encoder import EncodingResult, MemoryEncoder
 from surreal_memory.engine.reflex_activation import CoActivation, ReflexActivation
 from surreal_memory.engine.retrieval import DepthLevel, ReflexPipeline, RetrievalResult
 
-__version__ = "2.3.2"
+__version__ = "2.4.0"
 
 __all__ = [
     "__version__",

{surreal_memory-2.3.2 → surreal_memory-2.4.0}/src/surreal_memory/core/synapse.py

@@ -94,6 +94,8 @@ class Direction(StrEnum):
 
     UNIDIRECTIONAL = "uni"  # One-way: source -> target
     BIDIRECTIONAL = "bi"  # Two-way: source <-> target
+    FORWARD = "forward"  # legacy rows; also _row_to_synapse default in surrealdb store
+    BACKWARD = "backward"  # legacy rows: target -> source
 
 
 # Synapse types that are typically bidirectional

{surreal_memory-2.3.2 → surreal_memory-2.4.0}/src/surreal_memory/engine/consolidation.py

@@ -598,6 +598,14 @@ class ConsolidationEngine:
             states = await self._storage.get_neuron_states_batch(batch_ids)
 
             for neuron in batch:
+                # Never auto-prune pinned neurons, whether isolated (orphan) or
+                # dead. The dead-neuron path already honored pinned, but the
+                # orphan path short-circuited above it, so pinned isolated
+                # neurons were permanently deleted. Hoist the guard so it
+                # protects both paths.
+                if neuron.id in pinned_neuron_ids:
+                    continue
+
                 is_orphan = (
                     neuron.id not in connected_neuron_ids and neuron.id not in fiber_neuron_ids
                 )
@@ -606,9 +614,7 @@ class ConsolidationEngine:
                     orphan_ids.append(neuron.id)
                     continue
 
-                # Dead neuron: has connections but never accessed, old enough, not pinned
-                if neuron.id in pinned_neuron_ids:
-                    continue
+                # Dead neuron: has connections but never accessed, old enough
                 state = states.get(neuron.id)
                 freq = state.access_frequency if state else 0
                 if freq > 0:

{surreal_memory-2.3.2 → surreal_memory-2.4.0}/src/surreal_memory/engine/embedding/gemini_embedding.py

@@ -61,7 +61,21 @@ class GeminiEmbedding(EmbeddingProvider):
                     "Install it with: pip install 'surreal-memory[embeddings-gemini]'"
                 ) from exc
 
-            self._client = genai.Client(api_key=self._api_key)
+            # Optional gateway routing: honour GOOGLE_GEMINI_BASE_URL (the
+            # SDK env var) but build the client explicitly, because our
+            # gateway path already pins the API version — api_version must be
+            # emptied or the SDK doubles it ('/v1beta/v1beta/...').
+            base_url = os.getenv("GOOGLE_GEMINI_BASE_URL")
+            if base_url:
+                self._client = genai.Client(
+                    api_key=self._api_key,
+                    http_options={
+                        "base_url": base_url,
+                        "api_version": os.getenv("GOOGLE_GEMINI_API_VERSION", ""),
+                    },
+                )
+            else:
+                self._client = genai.Client(api_key=self._api_key)
 
         return self._client
 
@@ -94,13 +108,19 @@ class GeminiEmbedding(EmbeddingProvider):
         batch_size = 100
         for i in range(0, len(texts), batch_size):
             chunk = texts[i : i + batch_size]
-            # functools.partial binds `chunk` at creation (satisfies ruff B023,
-            # no loop-var late binding) and types cleanly for mypy.
+            # google-genai >= 2.0 folds a plain list[str] into ONE multi-part
+            # content (N texts -> 1 embedding); give each text its own content
+            # so the API returns one embedding per text. Plain ContentDicts are
+            # used instead of types.Content to avoid importing google.genai here
+            # (keeps this path working when the SDK is mocked/absent in tests).
+            chunk_contents = [{"parts": [{"text": t}]} for t in chunk]
+            # functools.partial binds the chunk at creation (satisfies ruff
+            # B023, no loop-var late binding) and types cleanly for mypy.
             response = await call_with_retry(
                 partial(
                     client.aio.models.embed_content,
                     model=self._model,
-                    contents=chunk,
+                    contents=chunk_contents,
                     config={"task_type": self._task_type},
                 ),
                 provider="gemini",

{surreal_memory-2.3.2 → surreal_memory-2.4.0}/src/surreal_memory/storage/base.py

@@ -304,6 +304,7 @@ class NeuralStorage(ABC):
         target_id: str | None = None,
         type: SynapseType | None = None,
         min_weight: float | None = None,
+        limit: int | None = None,
     ) -> list[Synapse]:
         """
         Find synapses matching criteria.
@@ -313,6 +314,7 @@ class NeuralStorage(ABC):
             target_id: Filter by target neuron
             type: Filter by synapse type
             min_weight: Filter by minimum weight
+            limit: Optional cap on number of returned synapses
 
         Returns:
             List of matching synapses

{surreal_memory-2.3.2 → surreal_memory-2.4.0}/src/surreal_memory/storage/memory_store.py

@@ -251,6 +251,7 @@ class InMemoryStorage(
         target_id: str | None = None,
         type: SynapseType | None = None,
         min_weight: float | None = None,
+        limit: int | None = None,
     ) -> list[Synapse]:
         brain_id = self._get_brain_id()
         results: list[Synapse] = []
@@ -266,6 +267,8 @@ class InMemoryStorage(
                 continue
             results.append(synapse)
 
+        if limit is not None:
+            return results[:limit]
         return results
 
     async def get_synapses_for_neurons(

{surreal_memory-2.3.2 → surreal_memory-2.4.0}/src/surreal_memory/storage/shared_store.py

@@ -316,6 +316,7 @@ class SharedStorage(SharedFiberBrainMixin, NeuralStorage):
         target_id: str | None = None,
         type: SynapseType | None = None,
         min_weight: float | None = None,
+        limit: int | None = None,
     ) -> list[Synapse]:
         """Find synapses matching criteria."""
         params: dict[str, Any] = {}
@@ -327,9 +328,14 @@ class SharedStorage(SharedFiberBrainMixin, NeuralStorage):
             params["type"] = type.value
         if min_weight is not None:
             params["min_weight"] = min_weight
+        if limit is not None:
+            params["limit"] = limit
 
         result = await self._request("GET", "/memory/synapses", params=params)
-        return [dict_to_synapse(s) for s in result.get("synapses", [])]
+        synapses = [dict_to_synapse(s) for s in result.get("synapses", [])]
+        if limit is not None:
+            return synapses[:limit]
+        return synapses
 
     async def update_synapse(self, synapse: Synapse) -> None:
         """Update an existing synapse."""

{surreal_memory-2.3.2 → surreal_memory-2.4.0}/src/surreal_memory/storage/sqlite_synapses.py

@@ -100,6 +100,7 @@ class SQLiteSynapseMixin:
         target_id: str | None = None,
         type: SynapseType | None = None,
         min_weight: float | None = None,
+        limit: int | None = None,
     ) -> list[Synapse]:
         conn = self._ensure_read_conn()
         brain_id = self._get_brain_id()
@@ -123,7 +124,11 @@ class SQLiteSynapseMixin:
             query += " AND weight >= ?"
             params.append(min_weight)
 
-        query += " LIMIT 10000"
+        if limit is not None:
+            query += " LIMIT ?"
+            params.append(limit)
+        else:
+            query += " LIMIT 10000"
 
         async with conn.execute(query, params) as cursor:
             rows = await cursor.fetchall()

{surreal_memory-2.3.2 → surreal_memory-2.4.0}/src/surreal_memory/storage/surrealdb/projects.py

@@ -22,6 +22,8 @@ logger = logging.getLogger(__name__)
 
 
 def _to_surreal_id(record_id: str) -> str:
+    if ":" in record_id:
+        record_id = record_id.rsplit(":", 1)[1]
     return record_id.replace("-", "_")
 
 

{surreal_memory-2.3.2 → surreal_memory-2.4.0}/src/surreal_memory/storage/surrealdb/schema.py

@@ -21,7 +21,7 @@ DEFINE FIELD brain_id        ON neuron TYPE string;
 DEFINE FIELD type            ON neuron TYPE string;
 DEFINE FIELD content         ON neuron TYPE string;
 DEFINE FIELD content_hash    ON neuron TYPE int DEFAULT 0;
-DEFINE FIELD metadata        ON neuron TYPE object DEFAULT {{}};
+DEFINE FIELD metadata        ON neuron TYPE object DEFAULT {};
 DEFINE FIELD embedding_vec   ON neuron TYPE option<array<float>>;
 DEFINE FIELD ephemeral       ON neuron TYPE bool DEFAULT false;
 DEFINE FIELD created_at      ON neuron TYPE datetime DEFAULT time::now();
@@ -54,23 +54,24 @@ DEFINE FIELD created_at        ON neuron_state TYPE datetime DEFAULT time::now()
 DEFINE INDEX idx_state_neuron  ON neuron_state FIELDS brain_id, neuron_id UNIQUE;
 
 -- Synapses (graph edges between neurons)
+-- Edge endpoints live in source_id/target_id (the fields the store reads and
+-- writes); they are declared here so the schema matches what is persisted, and
+-- the source/target indexes below cover the columns lookups actually use.
 DEFINE TABLE synapse SCHEMAFULL;
 DEFINE FIELD id           ON synapse TYPE string;
-DEFINE FIELD brain_id     ON synapse TYPE string;
+DEFINE FIELD brain_id     ON synapse TYPE string DEFAULT 'default';
 DEFINE FIELD type         ON synapse TYPE string;
+DEFINE FIELD source_id    ON synapse TYPE string;
+DEFINE FIELD target_id    ON synapse TYPE string;
 DEFINE FIELD weight       ON synapse TYPE float DEFAULT 1.0;
 DEFINE FIELD direction    ON synapse TYPE string DEFAULT 'forward';
-DEFINE FIELD metadata     ON synapse TYPE object DEFAULT {{}};
+DEFINE FIELD metadata     ON synapse TYPE object DEFAULT {};
 DEFINE FIELD created_at   ON synapse TYPE datetime DEFAULT time::now();
 DEFINE FIELD last_activated    ON synapse TYPE option<datetime>;
 DEFINE FIELD reinforced_count  ON synapse TYPE int DEFAULT 0;
 DEFINE INDEX idx_synapse_brain ON synapse FIELDS brain_id;
-DEFINE INDEX idx_synapse_source ON synapse FIELDS brain_id, out;
-DEFINE INDEX idx_synapse_target ON synapse FIELDS brain_id, in;
-
--- Synapse edge connections (for graph traversal)
-DEFINE TABLE connects_to SCHEMAFULL;
-DEFINE FIELD brain_id ON connects_to TYPE string;
+DEFINE INDEX idx_synapse_source ON synapse FIELDS brain_id, source_id;
+DEFINE INDEX idx_synapse_target ON synapse FIELDS brain_id, target_id;
 
 -- Fibers (memory clusters / signal pathways)
 DEFINE TABLE fiber SCHEMAFULL;
@@ -91,7 +92,7 @@ DEFINE FIELD summary         ON fiber TYPE option<string>;
 DEFINE FIELD essence         ON fiber TYPE option<string>;
 DEFINE FIELD auto_tags       ON fiber TYPE array<string> DEFAULT [];
 DEFINE FIELD agent_tags      ON fiber TYPE array<string> DEFAULT [];
-DEFINE FIELD metadata        ON fiber TYPE object DEFAULT {{}};
+DEFINE FIELD metadata        ON fiber TYPE object DEFAULT {};
 DEFINE FIELD compression_tier ON fiber TYPE int DEFAULT 0;
 DEFINE FIELD pinned           ON fiber TYPE bool DEFAULT false;
 DEFINE FIELD created_at       ON fiber TYPE datetime DEFAULT time::now();
@@ -103,8 +104,8 @@ DEFINE INDEX idx_fiber_anchor ON fiber FIELDS brain_id, anchor_neuron_id;
 DEFINE TABLE brain SCHEMAFULL;
 DEFINE FIELD id          ON brain TYPE string;
 DEFINE FIELD name        ON brain TYPE string;
-DEFINE FIELD config      ON brain TYPE object DEFAULT {{}};
-DEFINE FIELD metadata    ON brain TYPE object DEFAULT {{}};
+DEFINE FIELD config      ON brain TYPE object DEFAULT {};
+DEFINE FIELD metadata    ON brain TYPE object DEFAULT {};
 DEFINE FIELD created_at  ON brain TYPE datetime DEFAULT time::now();
 DEFINE FIELD updated_at  ON brain TYPE datetime DEFAULT time::now();
 -- Removed unique index on name - multiple brains can have same name
@@ -155,7 +156,7 @@ DEFINE FIELD source        ON typed_memory TYPE option<string>;
 DEFINE FIELD project_id    ON typed_memory TYPE option<string>;
 DEFINE FIELD expires_at    ON typed_memory TYPE option<datetime>;
 DEFINE FIELD tier          ON typed_memory TYPE string DEFAULT 'warm';
-DEFINE FIELD metadata      ON typed_memory TYPE object DEFAULT {{}};
+DEFINE FIELD metadata      ON typed_memory TYPE object DEFAULT {};
 DEFINE FIELD created_at    ON typed_memory TYPE datetime DEFAULT time::now();
 DEFINE FIELD updated_at    ON typed_memory TYPE datetime DEFAULT time::now();
 DEFINE INDEX idx_typed_brain ON typed_memory FIELDS brain_id;
@@ -181,7 +182,7 @@ DEFINE FIELD effective_date ON source TYPE option<datetime>;
 DEFINE FIELD expires_at     ON source TYPE option<datetime>;
 DEFINE FIELD status         ON source TYPE string DEFAULT 'active';
 DEFINE FIELD file_hash      ON source TYPE string DEFAULT '';
-DEFINE FIELD metadata       ON source TYPE object DEFAULT {{}};
+DEFINE FIELD metadata       ON source TYPE object DEFAULT {};
 DEFINE FIELD created_at     ON source TYPE datetime DEFAULT time::now();
 DEFINE FIELD updated_at     ON source TYPE datetime DEFAULT time::now();
 DEFINE INDEX idx_source_brain ON source FIELDS brain_id;
@@ -200,7 +201,7 @@ DEFINE FIELD created_at         ON alerts TYPE datetime DEFAULT time::now();
 DEFINE FIELD seen_at            ON alerts TYPE option<datetime>;
 DEFINE FIELD acknowledged_at    ON alerts TYPE option<datetime>;
 DEFINE FIELD resolved_at        ON alerts TYPE option<datetime>;
-DEFINE FIELD metadata           ON alerts TYPE object DEFAULT {{}};
+DEFINE FIELD metadata           ON alerts TYPE object DEFAULT {};
 DEFINE INDEX idx_alerts_brain   ON alerts FIELDS brain_id;
 DEFINE INDEX idx_alerts_status  ON alerts FIELDS brain_id, status;
 
@@ -275,7 +276,7 @@ DEFINE FIELD fiber_count     ON brain_versions TYPE int DEFAULT 0;
 DEFINE FIELD snapshot_hash   ON brain_versions TYPE string DEFAULT '';
 DEFINE FIELD snapshot_data   ON brain_versions TYPE string DEFAULT '';
 DEFINE FIELD created_at      ON brain_versions TYPE datetime DEFAULT time::now();
-DEFINE FIELD metadata        ON brain_versions TYPE object DEFAULT {{}};
+DEFINE FIELD metadata        ON brain_versions TYPE object DEFAULT {};
 DEFINE INDEX idx_versions_brain  ON brain_versions FIELDS brain_id;
 DEFINE INDEX idx_versions_number ON brain_versions FIELDS brain_id, version_number;
 

{surreal_memory-2.3.2 → surreal_memory-2.4.0}/src/surreal_memory/storage/surrealdb/sources.py

@@ -13,6 +13,8 @@ logger = logging.getLogger(__name__)
 
 
 def _to_surreal_id(record_id: str) -> str:
+    if ":" in record_id:
+        record_id = record_id.rsplit(":", 1)[1]
     return record_id.replace("-", "_")
 
 

{surreal_memory-2.3.2 → surreal_memory-2.4.0}/src/surreal_memory/storage/surrealdb/store.py

@@ -51,7 +51,13 @@ def _is_auth_error(exc: Exception) -> bool:
 
 
 def _to_surreal_id(record_id: str) -> str:
-    """Convert a UUID to a valid SurrealDB record name (alphanumeric + _-)."""
+    """Convert a record ID to a valid SurrealDB record name (alphanumeric + _-).
+
+    Strips any existing table prefix (e.g. 'neuron:abc-123' -> 'abc_123')
+    to prevent doubling when the caller later prepends 'neuron:'.
+    """
+    if ":" in record_id:
+        record_id = record_id.rsplit(":", 1)[1]
     return record_id.replace("-", "_")
 
 
@@ -92,6 +98,24 @@ def _ensure_naive(dt: datetime) -> datetime:
     return dt
 
 
+def _parse_neuron_type(value: Any) -> NeuronType:
+    """Parse a stored neuron type tolerantly.
+
+    External writers (e.g. an integration plugin) may store enum NAMES in
+    uppercase ('CONCEPT'); the engine stores enum VALUES ('concept'). Unknown
+    values fall back to CONCEPT instead of raising ValueError, so one foreign
+    row cannot break recall over the whole brain.
+    """
+    try:
+        return NeuronType(value)
+    except ValueError:
+        try:
+            return NeuronType(str(value).lower())
+        except ValueError:
+            logger.warning("Unknown neuron type %r — falling back to 'concept'", value)
+            return NeuronType.CONCEPT
+
+
 def _row_to_neuron(row: dict[str, Any]) -> Neuron:
     """Convert a SurrealDB neuron record to a Neuron."""
     meta = dict(row.get("metadata") or {})
@@ -108,7 +132,7 @@ def _row_to_neuron(row: dict[str, Any]) -> Neuron:
     neuron_id = neuron_id.replace("_", "-")
     return Neuron(
         id=neuron_id,
-        type=NeuronType(row["type"]),
+        type=_parse_neuron_type(row["type"]),
         content=str(row["content"]),
         metadata=meta,
         content_hash=int(row.get("content_hash", 0)),
@@ -211,8 +235,9 @@ class SurrealDBStorage(
 ):
     """SurrealDB-backed storage for Surreal-Memory.
 
-    Multi-model: documents (neurons), graphs (synapses via RELATE),
-    and vector search (HNSW via embedding_vec) all in one database.
+    Multi-model: documents (neurons), graphs (synapses linking neurons via
+    source_id/target_id), and vector search (HNSW via embedding_vec) all in
+    one database.
 
     Usage:
         storage = SurrealDBStorage(url="http://localhost:8001", ...)
@@ -564,14 +589,8 @@ class SurrealDBStorage(
             brain_id=brain_id,
             nid=sid,
         )
-        # Delete related edges
-        await self._query(
-            "DELETE connects_to WHERE out = $src OR in = $tgt",
-            src=f"neuron:{sid}",
-            tgt=f"neuron:{sid}",
-        )
-        # Delete state
-        await self._query(f"DELETE neuron_state:{sid}")
+        # Delete state (record id is state_<sid>, matching the writer in add_neuron)
+        await self._query(f"DELETE neuron_state:state_{sid}")
 
         try:
             await conn.delete(f"neuron:{sid}")
@@ -597,7 +616,7 @@ class SurrealDBStorage(
         conn = self._ensure_conn()
         sid = _to_surreal_id(neuron_id)
         try:
-            result = await conn.select(f"neuron_state:{sid}")
+            result = await conn.select(f"neuron_state:state_{sid}")
             if result:
                 return _row_to_neuron_state(result[0] if isinstance(result, list) else result)
         except Exception:
@@ -621,7 +640,7 @@ class SurrealDBStorage(
         if state.refractory_until:
             update_data["refractory_until"] = state.refractory_until
 
-        await conn.merge(f"neuron_state:{sid}", update_data)
+        await conn.merge(f"neuron_state:state_{sid}", update_data)
 
     # ================================================================
     # Synapse Operations
@@ -649,17 +668,6 @@ class SurrealDBStorage(
         }
         await conn.insert("synapse", record_data)
 
-        # Create graph edge for traversal
-        try:
-            await self._query(
-                "RELATE neuron:$src -> connects_to -> neuron:$tgt SET brain_id = $brain_id",
-                src=ss,
-                tgt=st,
-                brain_id=brain_id,
-            )
-        except Exception:
-            pass
-
         await self._record_change_internal("synapse", synapse.id, "insert", synapse)
         return synapse.id
 
@@ -680,6 +688,7 @@ class SurrealDBStorage(
         target_id: str | None = None,
         type: SynapseType | None = None,
         min_weight: float | None = None,
+        limit: int | None = None,
     ) -> list[Synapse]:
         brain_id = self._get_brain_id()
         conditions = ["brain_id = $brain_id"]
@@ -699,7 +708,10 @@ class SurrealDBStorage(
             params["min_weight"] = min_weight
 
         where = " AND ".join(conditions)
-        rows = await self._query(f"SELECT * FROM synapse WHERE {where}", **params)
+        query_str = f"SELECT * FROM synapse WHERE {where}"
+        if limit is not None:
+            query_str += f" LIMIT {limit}"
+        rows = await self._query(query_str, **params)
         return [_row_to_synapse(r) for r in rows]
 
     async def update_synapse(self, synapse: Synapse) -> None:
@@ -1105,7 +1117,7 @@ class SurrealDBStorage(
             try:
                 neuron = Neuron(
                     id=str(nd.get("id", "")),
-                    type=NeuronType(nd["type"]),
+                    type=_parse_neuron_type(nd["type"]),
                     content=str(nd["content"]),
                     metadata=dict(nd.get("metadata") or {}),
                     created_at=_parse_datetime(nd.get("created_at")) or utcnow(),