ladybug-memory 0.1.0__tar.gz

ladybug_memory-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+*.swp
+*.swo
+*~
+*.swn
+*.pyc
+.coverage
+.ropeproject
+*.egg-info
+.tox
+build
+.DS_Store
+dist/
+uv.lock

ladybug_memory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ladybug Memory, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ladybug_memory-0.1.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: ladybug-memory
+Version: 0.1.0
+Summary: Agent memory interface with implementations based on mem0 and engram
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: fastembed
+Requires-Dist: real-ladybug>=0.14.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Memory
+
+Agent memory interface with implementations based on mem0 and engram APIs.
+
+## Installation
+
+```bash
+uv sync
+```
+
+## Usage
+
+```python
+from memory import LadybugMemory
+
+mem = LadybugMemory("memory.lbug")
+
+mem.store("User prefers Python", memory_type="preference", importance=8)
+
+results = mem.search("python")
+for r in results:
+    print(r.entry.content)
+```

ladybug_memory-0.1.0/README.md

@@ -0,0 +1,23 @@
+# Memory
+
+Agent memory interface with implementations based on mem0 and engram APIs.
+
+## Installation
+
+```bash
+uv sync
+```
+
+## Usage
+
+```python
+from memory import LadybugMemory
+
+mem = LadybugMemory("memory.lbug")
+
+mem.store("User prefers Python", memory_type="preference", importance=8)
+
+results = mem.search("python")
+for r in results:
+    print(r.entry.content)
+```

ladybug_memory-0.1.0/example.py

@@ -0,0 +1,38 @@
+from memory import LadybugMemory
+
+
+def main() -> None:
+    mem = LadybugMemory("memory.lbdb")
+
+    mem.store(
+        "User prefers Python for data analysis", memory_type="preference", importance=8
+    )
+    mem.store("User is allergic to nuts", memory_type="preference", importance=9)
+    mem.store("Fixed bug in login handler", memory_type="work", importance=7)
+    mem.store(
+        "The python is a large snake found in tropical regions",
+        memory_type="fact",
+        importance=5,
+    )
+
+    print("=== Keyword Search for 'python' ===")
+    results = mem.search("python")
+    for r in results:
+        print(f"  - {r.entry.content} (score: {r.score})")
+
+    print("\n=== Semantic Search for 'snake' ===")
+    results = mem.semantic_search("snake", limit=3)
+    for r in results:
+        print(f"  - {r.entry.content} (score: {r.score:.4f})")
+
+    print("\nRecall all memories:")
+    for entry in mem.recall():
+        print(
+            f"  - [{entry.memory_type}] {entry.content} (importance: {entry.importance})"
+        )
+
+    print(f"\nTotal memories: {mem.count()}")
+
+
+if __name__ == "__main__":
+    main()

ladybug_memory-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "ladybug-memory"
+version = "0.1.0"
+description = "Agent memory interface with implementations based on mem0 and engram"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "real-ladybug>=0.14.0",
+    "fastembed",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "ruff>=0.1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/memory"]
+
+[tool.uv]
+dev-dependencies = [
+    "pytest>=7.0.0",
+    "ruff>=0.1.0",
+]

ladybug_memory-0.1.0/src/memory/__init__.py

@@ -0,0 +1,9 @@
+from memory.interface import AgentMemory, MemoryEntry, MemorySearchResult
+from memory.ladybug import LadybugMemory
+
+__all__ = [
+    "AgentMemory",
+    "MemoryEntry",
+    "MemorySearchResult",
+    "LadybugMemory",
+]

ladybug_memory-0.1.0/src/memory/interface.py

@@ -0,0 +1,100 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class MemoryEntry:
+    id: str
+    content: str
+    memory_type: str = "general"
+    importance: int = 5
+    metadata: dict[str, Any] | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+@dataclass
+class MemorySearchResult:
+    entry: MemoryEntry
+    score: float = 1.0
+
+
+class AgentMemory(ABC):
+    @abstractmethod
+    def store(
+        self,
+        content: str,
+        memory_type: str = "general",
+        importance: int = 5,
+        metadata: dict[str, Any] | None = None,
+    ) -> MemoryEntry:
+        pass
+
+    @abstractmethod
+    def search(
+        self,
+        query: str,
+        limit: int = 5,
+        memory_type: str | None = None,
+    ) -> list[MemorySearchResult]:
+        pass
+
+    @abstractmethod
+    def semantic_search(
+        self,
+        query: str,
+        limit: int = 5,
+        memory_type: str | None = None,
+    ) -> list[MemorySearchResult]:
+        pass
+
+    @abstractmethod
+    def recall(
+        self,
+        limit: int = 10,
+        min_importance: int = 0,
+        memory_type: str | None = None,
+    ) -> list[MemoryEntry]:
+        pass
+
+    @abstractmethod
+    def get(self, memory_id: str) -> MemoryEntry | None:
+        pass
+
+    @abstractmethod
+    def update(
+        self,
+        memory_id: str,
+        content: str | None = None,
+        importance: int | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> MemoryEntry | None:
+        pass
+
+    @abstractmethod
+    def delete(self, memory_id: str) -> bool:
+        pass
+
+    @abstractmethod
+    def link(
+        self,
+        source_id: str,
+        target_id: str,
+        relation: str = "related",
+    ) -> bool:
+        pass
+
+    @abstractmethod
+    def get_related(
+        self,
+        memory_id: str,
+        relation: str | None = None,
+        max_depth: int = 1,
+    ) -> list[tuple[MemoryEntry, str]]:
+        pass
+
+    @abstractmethod
+    def count(self) -> int:
+        pass

ladybug_memory-0.1.0/src/memory/ladybug.py

@@ -0,0 +1,405 @@
+import os
+import uuid
+from datetime import datetime
+from typing import Any, cast
+
+import real_ladybug as lb
+from fastembed import TextEmbedding
+
+from memory.interface import (
+    AgentMemory,
+    MemoryEntry,
+    MemorySearchResult,
+)
+
+
+def _get_result(result: lb.QueryResult | list[lb.QueryResult]) -> lb.QueryResult:
+    if isinstance(result, list):
+        return result[0]
+    return result
+
+
+class LadybugMemory(AgentMemory):
+    def __init__(self, db_path: str):
+        self.db = lb.Database(db_path)
+        self.conn = lb.Connection(self.db)
+        self._init_schema()
+        self._init_fts_index()
+        self._init_vector_search()
+
+    def _init_schema(self) -> None:
+        self.conn.execute("INSTALL JSON; LOAD EXTENSION JSON;")
+        self.conn.execute("INSTALL FTS; LOAD EXTENSION FTS;")
+        self.conn.execute("INSTALL vector; LOAD EXTENSION vector;")
+        self.conn.execute(
+            """
+            CREATE NODE TABLE IF NOT EXISTS Memory(
+                id STRING PRIMARY KEY,
+                content STRING,
+                memory_type STRING,
+                importance INT64,
+                metadata JSON,
+                embedding FLOAT[384],
+                created_at TIMESTAMP,
+                updated_at TIMESTAMP
+            )
+            """
+        )
+        self.conn.execute(
+            """
+            CREATE REL TABLE IF NOT EXISTS MemoryLink(
+                FROM Memory TO Memory,
+                relation STRING
+            )
+            """
+        )
+
+    def _init_fts_index(self) -> None:
+        try:
+            self.conn.execute(
+                """
+                CALL CREATE_FTS_INDEX(
+                    'Memory',
+                    'memory_content_fts',
+                    ['content'],
+                    stemmer := 'porter'
+                )
+                """
+            )
+        except Exception:
+            pass
+
+    def _init_embedding_model(self) -> None:
+        self._embedding_model = TextEmbedding("BAAI/bge-small-en-v1.5")
+
+    def _get_embedding(self, text: str) -> list[float]:
+        if not hasattr(self, "_embedding_model"):
+            self._init_embedding_model()
+        embeddings = list(self._embedding_model.embed([text]))
+        return embeddings[0]
+
+    def _init_vector_search(self) -> None:
+        try:
+            self.conn.execute(
+                """
+                CALL CREATE_VECTOR_INDEX(
+                    'Memory',
+                    'memory_content_index',
+                    'embedding',
+                    metric := 'cosine'
+                )
+                """
+            )
+        except Exception:
+            pass
+
+    def _row_to_entry(self, row: list | dict) -> MemoryEntry:
+        if isinstance(row, dict):
+            return MemoryEntry(
+                id=cast(str, row.get("id")),
+                content=cast(str, row.get("content")),
+                memory_type=cast(str, row.get("memory_type")),
+                importance=cast(int, row.get("importance")),
+                metadata=row.get("metadata"),
+                created_at=cast(datetime, row.get("created_at")),
+                updated_at=cast(datetime, row.get("updated_at")),
+            )
+        return MemoryEntry(
+            id=str(row[0]),
+            content=str(row[1]),
+            memory_type=str(row[2]),
+            importance=int(row[3]),
+            metadata=row[4],
+            created_at=row[5] if isinstance(row[5], datetime) else None,
+            updated_at=row[6] if isinstance(row[6], datetime) else None,
+        )
+
+    def store(
+        self,
+        content: str,
+        memory_type: str = "general",
+        importance: int = 5,
+        metadata: dict[str, Any] | None = None,
+    ) -> MemoryEntry:
+        memory_id = str(uuid.uuid4())
+        now = datetime.now()
+        metadata_json = f"CAST('{str(metadata)}' AS JSON)" if metadata else "NULL"
+        embedding = self._get_embedding(content)
+        embedding_str = "[" + ",".join(str(x) for x in embedding) + "]"
+
+        self.conn.execute(
+            f"""
+            CREATE (m:Memory {{
+                id: '{memory_id}',
+                content: '{content.replace("'", "''")}',
+                memory_type: '{memory_type}',
+                importance: {importance},
+                metadata: {metadata_json},
+                embedding: {embedding_str},
+                created_at: timestamp('{now.strftime("%Y-%m-%d %H:%M:%S")}'),
+                updated_at: timestamp('{now.strftime("%Y-%m-%d %H:%M:%S")}')
+            }})
+            RETURN m.id
+            """
+        )
+
+        return MemoryEntry(
+            id=memory_id,
+            content=content,
+            memory_type=memory_type,
+            importance=importance,
+            metadata=metadata,
+            created_at=now,
+            updated_at=now,
+        )
+
+    def search(
+        self,
+        query: str,
+        limit: int = 5,
+        memory_type: str | None = None,
+    ) -> list[MemorySearchResult]:
+        if memory_type:
+            cypher = f"""
+                CALL QUERY_FTS_INDEX('Memory', 'memory_content_fts', '{query.replace("'", "''")}', top := {limit})
+                WITH node AS m, score
+                WHERE m.memory_type = '{memory_type}'
+                RETURN m.id, m.content, m.memory_type, m.importance, m.metadata, m.created_at, m.updated_at, score
+                ORDER BY score DESC
+            """
+        else:
+            cypher = f"""
+                CALL QUERY_FTS_INDEX('Memory', 'memory_content_fts', '{query.replace("'", "''")}', top := {limit})
+                WITH node AS m, score
+                RETURN m.id, m.content, m.memory_type, m.importance, m.metadata, m.created_at, m.updated_at, score
+                ORDER BY score DESC
+            """
+
+        raw_result = self.conn.execute(cypher)
+        result = _get_result(raw_result)
+        search_results = []
+
+        while result.has_next():
+            row = result.get_next()
+            entry = self._row_to_entry(row)
+            score = float(row[7]) if len(row) > 7 else 1.0
+            search_results.append(MemorySearchResult(entry=entry, score=score))
+
+        return search_results
+
+    def semantic_search(
+        self,
+        query: str,
+        limit: int = 5,
+        memory_type: str | None = None,
+    ) -> list[MemorySearchResult]:
+        query_embedding = self._get_embedding(query)
+        embedding_str = "[" + ",".join(str(x) for x in query_embedding) + "]"
+
+        if memory_type:
+            cypher = f"""
+                CALL QUERY_VECTOR_INDEX(
+                    'Memory',
+                    'memory_content_index',
+                    {embedding_str},
+                    {limit}
+                )
+                WITH node AS m, distance
+                WHERE m.memory_type = '{memory_type}'
+                RETURN m.id, m.content, m.memory_type, m.importance, m.metadata, m.created_at, m.updated_at, distance
+                ORDER BY distance
+            """
+        else:
+            cypher = f"""
+                CALL QUERY_VECTOR_INDEX(
+                    'Memory',
+                    'memory_content_index',
+                    {embedding_str},
+                    {limit}
+                )
+                WITH node AS m, distance
+                RETURN m.id, m.content, m.memory_type, m.importance, m.metadata, m.created_at, m.updated_at, distance
+                ORDER BY distance
+            """
+
+        raw_result = self.conn.execute(cypher)
+        result = _get_result(raw_result)
+        search_results = []
+
+        while result.has_next():
+            row = result.get_next()
+            entry = self._row_to_entry(row)
+            distance = float(row[7]) if len(row) > 7 else 0.0
+            score = 1.0 / (1.0 + distance)
+            search_results.append(MemorySearchResult(entry=entry, score=score))
+
+        return search_results
+
+    def recall(
+        self,
+        limit: int = 10,
+        min_importance: int = 0,
+        memory_type: str | None = None,
+    ) -> list[MemoryEntry]:
+        if memory_type:
+            cypher = f"""
+                MATCH (m:Memory)
+                WHERE m.memory_type = '{memory_type}'
+                AND m.importance >= {min_importance}
+                RETURN m.id, m.content, m.memory_type, m.importance, m.metadata, m.created_at, m.updated_at
+                ORDER BY m.importance DESC, m.created_at DESC
+                LIMIT {limit}
+            """
+        else:
+            cypher = f"""
+                MATCH (m:Memory)
+                WHERE m.importance >= {min_importance}
+                RETURN m.id, m.content, m.memory_type, m.importance, m.metadata, m.created_at, m.updated_at
+                ORDER BY m.importance DESC, m.created_at DESC
+                LIMIT {limit}
+            """
+
+        raw_result = self.conn.execute(cypher)
+        result = _get_result(raw_result)
+        entries = []
+
+        while result.has_next():
+            row = result.get_next()
+            entries.append(self._row_to_entry(row))
+
+        return entries
+
+    def get(self, memory_id: str) -> MemoryEntry | None:
+        cypher = f"""
+            MATCH (m:Memory)
+            WHERE m.id = '{memory_id}'
+            RETURN m.id, m.content, m.memory_type, m.importance, m.metadata, m.created_at, m.updated_at
+        """
+
+        raw_result = self.conn.execute(cypher)
+        result = _get_result(raw_result)
+
+        if result.has_next():
+            row = result.get_next()
+            return self._row_to_entry(row)
+
+        return None
+
+    def update(
+        self,
+        memory_id: str,
+        content: str | None = None,
+        importance: int | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> MemoryEntry | None:
+        updates = []
+
+        if content is not None:
+            updates.append(f"m.content = '{content.replace("'", "''")}'")
+        if importance is not None:
+            updates.append(f"m.importance = {importance}")
+        if metadata is not None:
+            updates.append(f"m.metadata = CAST('{str(metadata)}' AS JSON)")
+
+        if not updates:
+            return self.get(memory_id)
+
+        now = datetime.now()
+        updates.append(
+            f"m.updated_at = timestamp('{now.strftime('%Y-%m-%d %H:%M:%S')}')"
+        )
+
+        cypher = f"""
+            MATCH (m:Memory)
+            WHERE m.id = '{memory_id}'
+            SET {", ".join(updates)}
+            RETURN m.id, m.content, m.memory_type, m.importance, m.metadata, m.created_at, m.updated_at
+        """
+
+        raw_result = self.conn.execute(cypher)
+        result = _get_result(raw_result)
+
+        if result.has_next():
+            row = result.get_next()
+            return self._row_to_entry(row)
+
+        return None
+
+    def delete(self, memory_id: str) -> bool:
+        cypher = f"""
+            MATCH (m:Memory)
+            WHERE m.id = '{memory_id}'
+            DELETE m
+        """
+
+        self.conn.execute(cypher)
+        return True
+
+    def link(
+        self,
+        source_id: str,
+        target_id: str,
+        relation: str = "related",
+    ) -> bool:
+        cypher = f"""
+            MATCH (a:Memory), (b:Memory)
+            WHERE a.id = '{source_id}' AND b.id = '{target_id}'
+            CREATE (a)-[r:MemoryLink {{relation: '{relation}'}}]->(b)
+        """
+
+        self.conn.execute(cypher)
+        return True
+
+    def get_related(
+        self,
+        memory_id: str,
+        relation: str | None = None,
+        max_depth: int = 1,
+    ) -> list[tuple[MemoryEntry, str]]:
+        if relation:
+            cypher = f"""
+                MATCH (m:Memory)-[r:MemoryLink {{relation: '{relation}'}}]->(related:Memory)
+                WHERE m.id = '{memory_id}'
+                RETURN related.id, related.content, related.memory_type, related.importance, related.metadata, related.created_at, related.updated_at, r.relation
+            """
+        else:
+            cypher = f"""
+                MATCH (m:Memory)-[r:MemoryLink]->(related:Memory)
+                WHERE m.id = '{memory_id}'
+                RETURN related.id, related.content, related.memory_type, related.importance, related.metadata, related.created_at, related.updated_at, r.relation
+            """
+
+        raw_result = self.conn.execute(cypher)
+        result = _get_result(raw_result)
+        related = []
+
+        while result.has_next():
+            row = result.get_next()
+            entry = MemoryEntry(
+                id=str(row[0]),
+                content=str(row[1]),
+                memory_type=str(row[2]),
+                importance=int(row[3]),
+                metadata=row[4],
+                created_at=row[5] if isinstance(row[5], datetime) else None,
+                updated_at=row[6] if isinstance(row[6], datetime) else None,
+            )
+            relation_type = str(row[7])
+            related.append((entry, relation_type))
+
+        return related
+
+    def count(self) -> int:
+        cypher = """
+            MATCH (m:Memory)
+            RETURN count(m)
+        """
+
+        raw_result = self.conn.execute(cypher)
+        result = _get_result(raw_result)
+
+        if result.has_next():
+            row = result.get_next()
+            return int(row[0])
+
+        return 0