lmem 0.2.1__tar.gz

lmem-0.2.1/.gitignore

@@ -0,0 +1,15 @@
+/target
+**/*.rs.bk
+*.db
+*.db-wal
+*.db-shm
+.DS_Store
+.fastembed_cache/
+**/.fastembed_cache/
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+/python/dist/
+/python/build/
+.pytest_cache/

lmem-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pathi Krishna Kanth
+
+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.

lmem-0.2.1/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: lmem
+Version: 0.2.1
+Summary: Ultra-Fast Local AI Agent Persistent Memory Engine with Neural Extractive QA & Knowledge Graph
+Project-URL: Homepage, https://github.com/krishnakanthpathi/lightmem
+Project-URL: Repository, https://github.com/krishnakanthpathi/lightmem
+Project-URL: Issues, https://github.com/krishnakanthpathi/lightmem/issues
+Author-email: Pathi Krishna Kanth <krishnakanthpathi@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,extractive-qa,fastembed,knowledge-graph,llm,memory,onnx,rag,sqlite
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# LightMem (`lmem`) Python SDK
+
+Ultra-Fast Local AI Agent Persistent Memory Engine with Neural Extractive QA & Knowledge Graph.
+
+[![PyPI version](https://img.shields.io/pypi/v/lmem.svg)](https://pypi.org/project/lmem/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## ⚡ Quickstart
+
+### Installation
+```bash
+pip install lmem
+```
+
+### Python SDK Usage
+
+```python
+from lmem import LightMem
+
+# Initialize vault (defaults to ~/.lightmem/memories.db or custom path)
+lm = LightMem()
+
+# 1. Store a memory (auto-infers 14 categories)
+memory = lm.remember(
+    "PostgreSQL primary runs on port 5432 with WAL archiving enabled",
+    category="fact",
+    title="PostgreSQL Primary Config",
+    tags=["postgres", "database", "production"],
+    confidence=0.95,
+)
+print("Stored memory:", memory.id)
+
+# 2. Hybrid Search (FTS5 BM25 + Vector Cosine RRF)
+results = lm.recall("postgres port", limit=5)
+for r in results:
+    print(f"[{r.score:.2f}] {r.memory.title}: {r.memory.content}")
+
+# 3. Neural Extractive QA (exact fact extraction in ~6ms via ONNX SQuAD2)
+answer = lm.answer("what port does postgresql use?")
+print("Extracted answer:", answer.answer)      # "5432"
+print("Confidence:", answer.confidence)
+print("Reranker:", answer.reranker_used)
+
+# 4. Knowledge Graph Autolink (title mentions, shared tags, vector similarity)
+link_stats = lm.autolink(min_similarity=0.75)
+print("Connections created:", link_stats)
+
+# 5. Multi-Hop Graph Traversal
+related = lm.related(memory.id, hops=2)
+for rel in related:
+    print(f"Hop {rel.distance}: {rel.memory.title} via {' -> '.join(rel.relation_path)}")
+
+# 6. Deploy Skill to AI Agents (Antigravity, Codex, Hermes, Cursor, Claude)
+lm.connect("antigravity")
+```
+
+---
+
+## 💻 CLI Commands (Included)
+
+The `pip install lmem` package also installs the standalone CLI:
+
+```bash
+lmem remember "Redis cache runs on port 6379" -t fact
+lmem recall "redis port" -l 5
+lmem answer "what is my pan card no"
+lmem autolink
+lmem graph
+lmem connect all
+```
+
+---
+
+## 📄 License
+MIT License. Created by Pathi Krishna Kanth.

lmem-0.2.1/README.md

@@ -0,0 +1,77 @@
+# LightMem (`lmem`) Python SDK
+
+Ultra-Fast Local AI Agent Persistent Memory Engine with Neural Extractive QA & Knowledge Graph.
+
+[![PyPI version](https://img.shields.io/pypi/v/lmem.svg)](https://pypi.org/project/lmem/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## ⚡ Quickstart
+
+### Installation
+```bash
+pip install lmem
+```
+
+### Python SDK Usage
+
+```python
+from lmem import LightMem
+
+# Initialize vault (defaults to ~/.lightmem/memories.db or custom path)
+lm = LightMem()
+
+# 1. Store a memory (auto-infers 14 categories)
+memory = lm.remember(
+    "PostgreSQL primary runs on port 5432 with WAL archiving enabled",
+    category="fact",
+    title="PostgreSQL Primary Config",
+    tags=["postgres", "database", "production"],
+    confidence=0.95,
+)
+print("Stored memory:", memory.id)
+
+# 2. Hybrid Search (FTS5 BM25 + Vector Cosine RRF)
+results = lm.recall("postgres port", limit=5)
+for r in results:
+    print(f"[{r.score:.2f}] {r.memory.title}: {r.memory.content}")
+
+# 3. Neural Extractive QA (exact fact extraction in ~6ms via ONNX SQuAD2)
+answer = lm.answer("what port does postgresql use?")
+print("Extracted answer:", answer.answer)      # "5432"
+print("Confidence:", answer.confidence)
+print("Reranker:", answer.reranker_used)
+
+# 4. Knowledge Graph Autolink (title mentions, shared tags, vector similarity)
+link_stats = lm.autolink(min_similarity=0.75)
+print("Connections created:", link_stats)
+
+# 5. Multi-Hop Graph Traversal
+related = lm.related(memory.id, hops=2)
+for rel in related:
+    print(f"Hop {rel.distance}: {rel.memory.title} via {' -> '.join(rel.relation_path)}")
+
+# 6. Deploy Skill to AI Agents (Antigravity, Codex, Hermes, Cursor, Claude)
+lm.connect("antigravity")
+```
+
+---
+
+## 💻 CLI Commands (Included)
+
+The `pip install lmem` package also installs the standalone CLI:
+
+```bash
+lmem remember "Redis cache runs on port 6379" -t fact
+lmem recall "redis port" -l 5
+lmem answer "what is my pan card no"
+lmem autolink
+lmem graph
+lmem connect all
+```
+
+---
+
+## 📄 License
+MIT License. Created by Pathi Krishna Kanth.

lmem-0.2.1/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "lmem"
+version = "0.2.1"
+description = "Ultra-Fast Local AI Agent Persistent Memory Engine with Neural Extractive QA & Knowledge Graph"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Pathi Krishna Kanth", email = "krishnakanthpathi@gmail.com" }
+]
+requires-python = ">=3.8"
+keywords = [
+    "agent",
+    "memory",
+    "ai",
+    "llm",
+    "rag",
+    "knowledge-graph",
+    "extractive-qa",
+    "sqlite",
+    "onnx",
+    "fastembed",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.scripts]
+lmem = "lmem.cli:main"
+lightmem = "lmem.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/krishnakanthpathi/lightmem"
+Repository = "https://github.com/krishnakanthpathi/lightmem"
+Issues = "https://github.com/krishnakanthpathi/lightmem/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lmem", "src/lightmem"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml",
+]

lmem-0.2.1/src/lightmem/__init__.py

@@ -0,0 +1,29 @@
+"""
+LightMem alias package re-exporting lmem.
+"""
+
+from lmem import (
+    LightMem,
+    Memory,
+    ScoredMemory,
+    AnswerResult,
+    RelatedMemory,
+    StorageStats,
+    PaginatedList,
+    MemoryInspection,
+    get_binary_path,
+    __version__,
+)
+
+__all__ = [
+    "LightMem",
+    "Memory",
+    "ScoredMemory",
+    "AnswerResult",
+    "RelatedMemory",
+    "StorageStats",
+    "PaginatedList",
+    "MemoryInspection",
+    "get_binary_path",
+    "__version__",
+]

lmem-0.2.1/src/lightmem/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561

lmem-0.2.1/src/lmem/__init__.py

@@ -0,0 +1,29 @@
+"""
+LightMem (lmem): Ultra-Fast Local AI Agent Persistent Memory Engine
+with Neural Extractive QA & Knowledge Graph.
+"""
+
+from .client import LightMem
+from .models import (
+    Memory,
+    ScoredMemory,
+    AnswerResult,
+    RelatedMemory,
+    StorageStats,
+    PaginatedList,
+    MemoryInspection,
+)
+from .binary import get_binary_path
+
+__version__ = "0.2.1"
+__all__ = [
+    "LightMem",
+    "Memory",
+    "ScoredMemory",
+    "AnswerResult",
+    "RelatedMemory",
+    "StorageStats",
+    "PaginatedList",
+    "MemoryInspection",
+    "get_binary_path",
+]

lmem-0.2.1/src/lmem/binary.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+import os
+import sys
+import shutil
+import platform
+import subprocess
+import urllib.request
+import tarfile
+import zipfile
+from pathlib import Path
+from typing import Optional, List, Tuple
+
+
+def get_binary_path() -> str:
+    """
+    Locates the `lmem` executable.
+    Checks:
+    1. Environment variable `LMEM_BINARY_PATH` or `LIGHTMEM_BINARY_PATH`
+    2. PATH (`which lmem`)
+    3. User local directory `~/.local/bin/lmem` or `~/.cargo/bin/lmem`
+    4. Auto-downloads prebuilt binary to `~/.lightmem/bin/lmem` if missing.
+    """
+    env_path = os.environ.get("LMEM_BINARY_PATH") or os.environ.get("LIGHTMEM_BINARY_PATH")
+    if env_path and os.path.isfile(env_path) and os.access(env_path, os.X_OK):
+        return env_path
+
+    which_path = shutil.which("lmem")
+    if which_path:
+        return which_path
+
+    home = Path.home()
+    candidate_paths = [
+        home / ".local" / "bin" / "lmem",
+        home / ".cargo" / "bin" / "lmem",
+        home / ".lightmem" / "bin" / "lmem",
+        home / ".lightmem" / "bin" / "lmem.exe",
+    ]
+
+    for p in candidate_paths:
+        if p.is_file() and os.access(str(p), os.X_OK):
+            return str(p)
+
+    # If not found, attempt to auto-download to ~/.lightmem/bin/lmem
+    try:
+        downloaded = ensure_binary_downloaded()
+        if downloaded and os.path.isfile(downloaded) and os.access(downloaded, os.X_OK):
+            return downloaded
+    except Exception as e:
+        pass
+
+    raise FileNotFoundError(
+        "Could not find the 'lmem' native binary on this system. "
+        "Install it via:\n"
+        "  curl -fsSL https://raw.githubusercontent.com/krishnakanthpathi/lightmem/neural-reranker/install.sh | sh\n"
+        "Or set the LMEM_BINARY_PATH environment variable."
+    )
+
+
+def ensure_binary_downloaded(version: str = "v0.2.1") -> str:
+    """Downloads pre-built release binary for current system into ~/.lightmem/bin/lmem."""
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+
+    if system == "darwin":
+        target = "aarch64-apple-darwin" if machine in ["arm64", "aarch64"] else "x86_64-apple-darwin"
+        archive_name = f"lmem-{target}.tar.gz"
+        exe_name = "lmem"
+    elif system == "linux":
+        target = "aarch64-unknown-linux-gnu" if machine in ["arm64", "aarch64"] else "x86_64-unknown-linux-gnu"
+        archive_name = f"lmem-{target}.tar.gz"
+        exe_name = "lmem"
+    elif system == "windows":
+        target = "x86_64-pc-windows-msvc"
+        archive_name = f"lmem-{target}.zip"
+        exe_name = "lmem.exe"
+    else:
+        raise RuntimeError(f"Unsupported OS: {system}")
+
+    dest_dir = Path.home() / ".lightmem" / "bin"
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest_exe = dest_dir / exe_name
+
+    if dest_exe.is_file() and os.access(str(dest_exe), os.X_OK):
+        return str(dest_exe)
+
+    url = f"https://github.com/krishnakanthpathi/lightmem/releases/download/{version}/{archive_name}"
+    tmp_archive = dest_dir / archive_name
+
+    try:
+        urllib.request.urlretrieve(url, tmp_archive)
+        if archive_name.endswith(".zip"):
+            with zipfile.ZipFile(tmp_archive, "r") as z:
+                z.extractall(dest_dir)
+        else:
+            with tarfile.open(tmp_archive, "r:gz") as t:
+                t.extractall(dest_dir)
+
+        tmp_archive.unlink(missing_ok=True)
+        dest_exe.chmod(0o755)
+        return str(dest_exe)
+    except Exception as e:
+        tmp_archive.unlink(missing_ok=True)
+        raise RuntimeError(f"Failed to auto-download lmem binary from {url}: {e}")
+
+
+def execute_lmem(args: List[str], input_text: Optional[str] = None) -> Tuple[int, str, str]:
+    binary = get_binary_path()
+    proc = subprocess.Popen(
+        [binary] + args,
+        stdin=subprocess.PIPE if input_text is not None else None,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    stdout, stderr = proc.communicate(input=input_text)
+    return proc.returncode, stdout, stderr

lmem-0.2.1/src/lmem/cli.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+import sys
+import subprocess
+from .binary import get_binary_path
+
+
+def main() -> None:
+    """CLI entrypoint for lmem Python package."""
+    try:
+        binary = get_binary_path()
+    except FileNotFoundError as e:
+        sys.stderr.write(f"Error: {e}\n")
+        sys.exit(1)
+
+    result = subprocess.call([binary] + sys.argv[1:])
+    sys.exit(result)
+
+
+if __name__ == "__main__":
+    main()

lmem-0.2.1/src/lmem/client.py

@@ -0,0 +1,269 @@
+from __future__ import annotations
+import json
+from typing import List, Optional, Dict, Any, Tuple
+from pathlib import Path
+
+from .binary import execute_lmem, get_binary_path
+from .models import (
+    Memory,
+    ScoredMemory,
+    AnswerResult,
+    RelatedMemory,
+    StorageStats,
+    PaginatedList,
+    MemoryInspection,
+)
+
+
+class LightMem:
+    """
+    LightMem: Ultra-Fast Local AI Agent Persistent Memory Engine.
+    Provides Pythonic methods for remember, recall, answer, graph, and maintenance.
+    """
+
+    def __init__(
+        self,
+        db_path: Optional[str | Path] = None,
+        global_db: bool = False,
+    ):
+        self.db_path = str(db_path) if db_path else None
+        self.global_db = global_db
+
+    @property
+    def binary_path(self) -> str:
+        return get_binary_path()
+
+    def _build_base_args(self) -> List[str]:
+        args: List[str] = []
+        if self.global_db:
+            args.append("--global")
+        elif self.db_path:
+            args.extend(["--db", self.db_path])
+        return args
+
+    def _call(self, subcommand: str, extra_args: List[str], input_text: Optional[str] = None) -> Any:
+        full_args = self._build_base_args() + [subcommand] + extra_args + ["--json"]
+        code, stdout, stderr = execute_lmem(full_args, input_text=input_text)
+        if code != 0:
+            err = stderr.strip() or stdout.strip()
+            raise RuntimeError(f"lmem {subcommand} failed (exit code {code}): {err}")
+        try:
+            return json.loads(stdout)
+        except json.JSONDecodeError as e:
+            raise RuntimeError(f"Failed to parse JSON output from lmem {subcommand}: {stdout}") from e
+
+    # 1. Store
+    def remember(
+        self,
+        content: str,
+        category: Optional[str] = None,
+        title: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        confidence: float = 0.9,
+        ttl: Optional[str] = None,
+        supersede: bool = False,
+    ) -> Memory:
+        args = [content]
+        if category:
+            args.extend(["-t", category])
+        if title:
+            args.extend(["--title", title])
+        if tags:
+            args.extend(["--tags", ",".join(tags)])
+        if confidence is not None:
+            args.extend(["--confidence", str(confidence)])
+        if ttl:
+            args.extend(["--ttl", ttl])
+        if supersede:
+            args.append("--supersede")
+
+        data = self._call("remember", args)
+        return Memory.from_dict(data)
+
+    # 2. Hybrid Recall
+    def recall(
+        self,
+        query: str,
+        limit: int = 5,
+        category: Optional[str] = None,
+        min_similarity: Optional[float] = None,
+        multi_hop: bool = False,
+        as_of: Optional[str] = None,
+        date: Optional[str] = None,
+    ) -> List[ScoredMemory]:
+        args = [query, "-l", str(limit)]
+        if category:
+            args.extend(["-t", category])
+        if min_similarity is not None:
+            args.extend(["--min-similarity", str(min_similarity)])
+        if multi_hop:
+            args.append("--multi-hop")
+        if as_of:
+            args.extend(["--as-of", as_of])
+        if date:
+            args.extend(["--date", date])
+
+        data = self._call("recall", args)
+        if isinstance(data, list):
+            return [ScoredMemory.from_dict(item) for item in data]
+        return []
+
+    # 3. Neural Extractive QA Answer
+    def answer(
+        self,
+        question: str,
+        category: Optional[str] = None,
+        reranker: Optional[str] = None,
+        limit: int = 10,
+        as_of: Optional[str] = None,
+        date: Optional[str] = None,
+    ) -> AnswerResult:
+        args = [question, "-l", str(limit)]
+        if category:
+            args.extend(["-t", category])
+        if reranker:
+            args.extend(["-r", reranker])
+        if as_of:
+            args.extend(["--as-of", as_of])
+        if date:
+            args.extend(["--date", date])
+
+        data = self._call("answer", args)
+        return AnswerResult.from_dict(data)
+
+    # 4. List
+    def list(
+        self,
+        page: Optional[int] = None,
+        limit: int = 20,
+        offset: int = 0,
+        category: Optional[str] = None,
+        status: str = "active",
+        as_of: Optional[str] = None,
+        date: Optional[str] = None,
+    ) -> PaginatedList:
+        args = ["-l", str(limit), "--status", status]
+        if page is not None:
+            args.extend(["--page", str(page)])
+        elif offset > 0:
+            args.extend(["--offset", str(offset)])
+        if category:
+            args.extend(["-t", category])
+        if as_of:
+            args.extend(["--as-of", as_of])
+        if date:
+            args.extend(["--date", date])
+
+        data = self._call("list", args)
+        items = [Memory.from_dict(item) for item in data.get("items", [])]
+        return PaginatedList(
+            items=items,
+            total=int(data.get("total", len(items))),
+            limit=int(data.get("limit", limit)),
+            offset=int(data.get("offset", offset)),
+            page=int(data.get("page", page or 1)),
+            total_pages=int(data.get("total_pages", 1)),
+            has_more=bool(data.get("has_more", False)),
+        )
+
+    # 5. Get Single Memory
+    def get(self, memory_id: str) -> Optional[Memory]:
+        try:
+            data = self._call("get", [memory_id])
+            return Memory.from_dict(data) if data else None
+        except RuntimeError:
+            return None
+
+    # 5b. Inspect Memory & Graph Links
+    def inspect(self, memory_id: str) -> Optional[MemoryInspection]:
+        try:
+            data = self._call("inspect", [memory_id])
+            return MemoryInspection.from_dict(data) if data else None
+        except RuntimeError:
+            return None
+
+    # 6. Forget (Soft or Hard)
+    def forget(self, memory_id: str, hard: bool = False) -> bool:
+        args = [memory_id]
+        if hard:
+            args.append("--hard")
+        data = self._call("forget", args)
+        return bool(data.get("success", False))
+
+    # 7. Deduplicate & Merge
+    def deduplicate(self) -> int:
+        data = self._call("dedup", [])
+        return int(data.get("merged", 0))
+
+    # 8. Nearest-Neighbor Conflicts
+    def conflicts(
+        self,
+        yes: bool = False,
+        min_similarity: float = 0.78,
+        reranker: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        args = ["--min-similarity", str(min_similarity)]
+        if yes:
+            args.append("--yes")
+        if reranker:
+            args.extend(["-r", reranker])
+        data = self._call("conflicts", args)
+        return data if isinstance(data, list) else []
+
+    # 9. Knowledge Graph Links
+    def link(
+        self,
+        source: str,
+        target: str,
+        relation: str = "relates_to",
+        weight: float = 1.0,
+    ) -> Tuple[str, str]:
+        args = [source, target, "-r", relation, "-w", str(weight)]
+        data = self._call("link", args)
+        return (data.get("source", source), data.get("target", target))
+
+    def unlink(self, source: str, target: str, relation: Optional[str] = None) -> bool:
+        args = [source, target]
+        if relation:
+            args.extend(["-r", relation])
+        data = self._call("unlink", args)
+        return bool(data.get("removed", False))
+
+    # 10. Multi-Hop Graph Traversal
+    def related(self, memory_id: str, hops: int = 2) -> List[RelatedMemory]:
+        data = self._call("related", [memory_id, "-n", str(hops)])
+        if isinstance(data, list):
+            return [RelatedMemory.from_dict(item) for item in data]
+        return []
+
+    # 11. Graph Snapshot
+    def graph(self, focus: Optional[str] = None, hops: int = 2) -> Dict[str, Any]:
+        args = ["-n", str(hops)]
+        if focus:
+            args.extend(["-f", focus])
+        return self._call("graph", args)
+
+    # 12. Autolink Vault
+    def autolink(self, min_similarity: float = 0.75) -> Dict[str, Any]:
+        return self._call("autolink", ["--min-similarity", str(min_similarity)])
+
+    # 13. Connect AI Agent Skills
+    def connect(
+        self,
+        platform: Optional[str] = None,
+        workspace: bool = False,
+        path: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        args = []
+        if platform:
+            args.append(platform)
+        if workspace:
+            args.append("--workspace")
+        if path:
+            args.extend(["--path", path])
+        return self._call("connect", args)
+
+    # 14. Vault Telemetry & Stats
+    def stats(self) -> StorageStats:
+        data = self._call("stats", [])
+        return StorageStats.from_dict(data)

lmem-0.2.1/src/lmem/models.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import List, Optional, Any, Dict
+
+
+@dataclass
+class Memory:
+    id: str
+    category: str
+    title: str
+    content: str
+    tags: List[str] = field(default_factory=list)
+    confidence: float = 0.9
+    status: str = "active"
+    provenance: str = "explicit_statement"
+    created_at: str = ""
+    updated_at: str = ""
+    expired_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> Memory:
+        mem_data = data.get("memory", data)
+        return cls(
+            id=mem_data.get("id", ""),
+            category=mem_data.get("category", "fact"),
+            title=mem_data.get("title", ""),
+            content=mem_data.get("content", ""),
+            tags=mem_data.get("tags", []),
+            confidence=float(mem_data.get("confidence", 0.9)),
+            status=mem_data.get("status", "active"),
+            provenance=mem_data.get("provenance", "explicit_statement"),
+            created_at=mem_data.get("created_at", ""),
+            updated_at=mem_data.get("updated_at", ""),
+            expired_at=mem_data.get("expired_at"),
+        )
+
+
+@dataclass
+class MemoryInspection:
+    memory: Memory
+    links: List[Dict[str, Any]]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> MemoryInspection:
+        return cls(
+            memory=Memory.from_dict(data.get("memory", data)),
+            links=data.get("links", []),
+        )
+
+
+@dataclass
+class ScoredMemory:
+    memory: Memory
+    score: float
+    vector_rank: Optional[int] = None
+    bm25_rank: Optional[int] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> ScoredMemory:
+        mem_data = data.get("memory", data)
+        return cls(
+            memory=Memory.from_dict(mem_data),
+            score=float(data.get("score", 0.0)),
+            vector_rank=data.get("vector_rank"),
+            bm25_rank=data.get("bm25_rank"),
+        )
+
+
+@dataclass
+class AnswerResult:
+    answer: str
+    confidence: float
+    reranker_used: str
+    selected_memory: Optional[Memory] = None
+
+    @property
+    def evidence(self) -> Optional[str]:
+        return self.selected_memory.content if self.selected_memory else None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> AnswerResult:
+        selected = data.get("selected_memory")
+        return cls(
+            answer=data.get("answer", ""),
+            confidence=float(data.get("confidence", 0.0)),
+            reranker_used=data.get("reranker_used", ""),
+            selected_memory=Memory.from_dict(selected) if selected else None,
+        )
+
+
+@dataclass
+class RelatedMemory:
+    memory: Memory
+    distance: int
+    relation_path: List[str]
+    score: float
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> RelatedMemory:
+        mem_data = data.get("memory", {})
+        return cls(
+            memory=Memory.from_dict(mem_data),
+            distance=int(data.get("distance", 1)),
+            relation_path=data.get("relation_path", []),
+            score=float(data.get("score", 1.0)),
+        )
+
+
+@dataclass
+class StorageStats:
+    total_memories: int
+    active_memories: int
+    expired_memories: int
+    vector_count: int
+    categories: Dict[str, int]
+    storage_size_bytes: int
+    db_path: str
+    backend: Optional[str] = None
+    embedding_model: Optional[str] = None
+    reranker: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> StorageStats:
+        return cls(
+            total_memories=int(data.get("total_memories", 0)),
+            active_memories=int(data.get("active_memories", 0)),
+            expired_memories=int(data.get("expired_memories", 0)),
+            vector_count=int(data.get("vector_count", 0)),
+            categories=data.get("categories", {}),
+            storage_size_bytes=int(data.get("storage_size_bytes", 0)),
+            db_path=data.get("db_path", ""),
+            backend=data.get("backend"),
+            embedding_model=data.get("embedding_model"),
+            reranker=data.get("reranker"),
+        )
+
+
+class PaginatedList(list):
+    """A list of items that also carries pagination metadata (total, page, etc.)."""
+    def __init__(
+        self,
+        items: List[Memory],
+        total: int = 0,
+        limit: int = 20,
+        offset: int = 0,
+        page: int = 1,
+        total_pages: int = 1,
+        has_more: bool = False,
+    ):
+        super().__init__(items)
+        self.total = total
+        self.limit = limit
+        self.offset = offset
+        self.page = page
+        self.total_pages = total_pages
+        self.has_more = has_more
+
+    @property
+    def items(self) -> List[Memory]:
+        return list(self)

lmem-0.2.1/src/lmem/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561