agentrecall-db 0.1.0__py3-none-any.whl

agentrecall/__init__.py

@@ -0,0 +1,33 @@
+"""agentrecall — agent memory in a single SQLite file.
+
+No vector DB, no server, no cloud. Keyword recall works out of the box on stdlib alone;
+install ``agentrecall[semantic]`` for torch-free hybrid semantic search.
+"""
+
+from __future__ import annotations
+
+from .embeddings import Embedder, Model2VecEmbedder, get_default_embedder
+from .errors import (
+    AgentRecallError,
+    EmbeddingsUnavailable,
+    MemoryNotFound,
+    StoreError,
+)
+from .memory import Memory
+from .models import MemoryHit, MemoryRecord
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Memory",
+    "MemoryRecord",
+    "MemoryHit",
+    "Embedder",
+    "Model2VecEmbedder",
+    "get_default_embedder",
+    "AgentRecallError",
+    "MemoryNotFound",
+    "EmbeddingsUnavailable",
+    "StoreError",
+    "__version__",
+]

agentrecall/cli.py

@@ -0,0 +1,209 @@
+"""``agentrecall`` command-line interface (argparse, stdlib only).
+
+All subcommands honour ``--db`` and the ``AGENTRECALL_*`` environment variables. Use
+``--json`` on read commands for machine-readable output.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime
+
+from . import __version__
+from .config import Settings
+from .memory import Memory
+
+
+def _split_tags(value: str | None) -> list[str] | None:
+    if not value:
+        return None
+    tags = [t.strip() for t in value.split(",") if t.strip()]
+    return tags or None
+
+
+def _build_memory(args: argparse.Namespace) -> Memory:
+    settings = Settings.from_env()
+    db_path = getattr(args, "db", None) or settings.db_path
+    namespace = getattr(args, "namespace", None) or settings.namespace
+    embeddings = settings.embeddings_value()
+    if getattr(args, "embeddings", None):
+        embeddings = {"auto": "auto", "true": True, "false": False}[args.embeddings]
+    return Memory(db_path, namespace=namespace, embeddings=embeddings)
+
+
+def _truncate(text: str, width: int = 80) -> str:
+    text = text.replace("\n", " ")
+    return text if len(text) <= width else text[: width - 1] + "…"
+
+
+def _cmd_add(args: argparse.Namespace) -> int:
+    with _build_memory(args) as mem:
+        record = mem.add(
+            args.content,
+            tags=_split_tags(args.tags),
+            importance=args.importance,
+        )
+    print(f"#{record.id}  {_truncate(record.content)}")
+    return 0
+
+
+def _cmd_search(args: argparse.Namespace) -> int:
+    with _build_memory(args) as mem:
+        hits = mem.search(args.query, k=args.k, tags=_split_tags(args.tags))
+    if args.json:
+        print(json.dumps([h.to_dict() for h in hits], ensure_ascii=False, indent=2))
+        return 0
+    if not hits:
+        print("(no matches)")
+        return 0
+    for hit in hits:
+        print(f"{hit.score:6.3f}  #{hit.id:<4} {_truncate(hit.content)}")
+    return 0
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    with _build_memory(args) as mem:
+        records = mem.all(limit=args.limit, tags=_split_tags(args.tags))
+    if args.json:
+        print(json.dumps([r.to_dict() for r in records], ensure_ascii=False, indent=2))
+        return 0
+    if not records:
+        print("(empty)")
+        return 0
+    for record in records:
+        tags = f"  [{', '.join(record.tags)}]" if record.tags else ""
+        print(f"#{record.id:<4} {_truncate(record.content)}{tags}")
+    return 0
+
+
+def _cmd_get(args: argparse.Namespace) -> int:
+    from .errors import MemoryNotFound
+
+    with _build_memory(args) as mem:
+        try:
+            record = mem.get(args.id)
+        except MemoryNotFound:
+            print(f"no memory with id {args.id}", file=sys.stderr)
+            return 1
+    print(json.dumps(record.to_dict(), ensure_ascii=False, indent=2))
+    return 0
+
+
+def _cmd_delete(args: argparse.Namespace) -> int:
+    with _build_memory(args) as mem:
+        ok = mem.delete(args.id)
+    print("deleted" if ok else "not found")
+    return 0 if ok else 1
+
+
+def _cmd_forget(args: argparse.Namespace) -> int:
+    before = datetime.fromisoformat(args.before) if args.before else None
+    with _build_memory(args) as mem:
+        removed = mem.forget(before=before, keep_last=args.keep_last)
+    print(f"forgot {removed} memorie(s)")
+    return 0
+
+
+def _cmd_stats(args: argparse.Namespace) -> int:
+    with _build_memory(args) as mem:
+        data = {
+            "namespace": mem.namespace,
+            "count": mem.count(),
+            "semantic": mem.semantic_enabled,
+        }
+    print(json.dumps(data, ensure_ascii=False, indent=2))
+    return 0
+
+
+def _cmd_export(args: argparse.Namespace) -> int:
+    with _build_memory(args) as mem:
+        records = mem.all()
+    if args.format == "json":
+        print(json.dumps([r.to_dict() for r in records], ensure_ascii=False, indent=2))
+    else:  # markdown
+        for record in records:
+            tags = f" `{' '.join(record.tags)}`" if record.tags else ""
+            print(f"- **#{record.id}**{tags} — {record.content}")
+    return 0
+
+
+def _cmd_serve(args: argparse.Namespace) -> int:
+    from .mcp_server import serve
+
+    mem = _build_memory(args)
+    try:
+        serve(mem, transport=args.transport)
+    finally:
+        mem.close()
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agentrecall",
+        description="Agent memory in a single SQLite file.",
+    )
+    parser.add_argument("--version", action="version", version=f"agentrecall {__version__}")
+    parser.add_argument("--db", help="database file (env AGENTRECALL_DB)")
+    parser.add_argument("--namespace", help="namespace (env AGENTRECALL_NAMESPACE)")
+    parser.add_argument(
+        "--embeddings", choices=["auto", "true", "false"], help="semantic search mode"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_add = sub.add_parser("add", help="store a memory")
+    p_add.add_argument("content")
+    p_add.add_argument("--tags", help="comma-separated tags")
+    p_add.add_argument("--importance", type=float, default=1.0)
+    p_add.set_defaults(func=_cmd_add)
+
+    p_search = sub.add_parser("search", help="search memories")
+    p_search.add_argument("query")
+    p_search.add_argument("-k", type=int, default=5)
+    p_search.add_argument("--tags", help="comma-separated tags filter")
+    p_search.add_argument("--json", action="store_true")
+    p_search.set_defaults(func=_cmd_search)
+
+    p_list = sub.add_parser("list", help="list memories")
+    p_list.add_argument("--limit", type=int, default=20)
+    p_list.add_argument("--tags", help="comma-separated tags filter")
+    p_list.add_argument("--json", action="store_true")
+    p_list.set_defaults(func=_cmd_list)
+
+    p_get = sub.add_parser("get", help="show one memory")
+    p_get.add_argument("id", type=int)
+    p_get.set_defaults(func=_cmd_get)
+
+    p_delete = sub.add_parser("delete", help="delete one memory")
+    p_delete.add_argument("id", type=int)
+    p_delete.set_defaults(func=_cmd_delete)
+
+    p_forget = sub.add_parser("forget", help="bulk-delete by age or count")
+    p_forget.add_argument("--before", help="ISO-8601 datetime; delete older")
+    p_forget.add_argument("--keep-last", type=int, dest="keep_last")
+    p_forget.set_defaults(func=_cmd_forget)
+
+    p_stats = sub.add_parser("stats", help="show counts and config")
+    p_stats.set_defaults(func=_cmd_stats)
+
+    p_export = sub.add_parser("export", help="dump memories")
+    p_export.add_argument("--format", choices=["json", "md"], default="json")
+    p_export.set_defaults(func=_cmd_export)
+
+    p_serve = sub.add_parser("serve", help="run the MCP server")
+    p_serve.add_argument("--transport", default="stdio")
+    p_serve.set_defaults(func=_cmd_serve)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

agentrecall/config.py

@@ -0,0 +1,42 @@
+"""Lightweight settings read from ``AGENTRECALL_*`` environment variables.
+
+Stdlib only — no pydantic, no extra dependency. Used by the CLI and MCP server so the
+same database can be configured once via the environment.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from .embeddings import DEFAULT_MODEL
+
+
+@dataclass
+class Settings:
+    db_path: str = "agentrecall.db"
+    namespace: str = "default"
+    embeddings: str = "auto"  # "auto" | "true" | "false"
+    model: str = DEFAULT_MODEL
+
+    @classmethod
+    def from_env(cls) -> Settings:
+        env = os.environ
+        return cls(
+            db_path=env.get("AGENTRECALL_DB", cls.db_path),
+            namespace=env.get("AGENTRECALL_NAMESPACE", cls.namespace),
+            embeddings=env.get("AGENTRECALL_EMBEDDINGS", cls.embeddings).lower(),
+            model=env.get("AGENTRECALL_MODEL", cls.model),
+        )
+
+    def embeddings_value(self) -> bool | str:
+        """Map the string setting to the ``Memory(embeddings=...)`` argument."""
+        value = self.embeddings.lower()
+        if value == "true":
+            return True
+        if value == "false":
+            return False
+        return "auto"
+
+
+__all__ = ["Settings"]

agentrecall/embeddings.py

@@ -0,0 +1,84 @@
+"""Embeddings for semantic recall — optional and torch-free.
+
+The default :class:`Model2VecEmbedder` wraps `model2vec <https://github.com/MinishLab/model2vec>`_
+static embeddings: ~10 MB models, CPU-only, no PyTorch. Bring your own embedder by passing
+any object that satisfies the :class:`Embedder` protocol to ``Memory(embedder=...)``.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from .errors import EmbeddingsUnavailable
+
+DEFAULT_MODEL = "minishlab/potion-base-8M"
+
+
+@runtime_checkable
+class Embedder(Protocol):
+    """Anything that can turn texts into fixed-length vectors.
+
+    Implementations must be deterministic for a given input and return one vector per
+    input text, each of length :attr:`dim`.
+    """
+
+    @property
+    def dim(self) -> int: ...
+
+    def embed(self, texts: list[str]) -> list[list[float]]: ...
+
+
+class Model2VecEmbedder:
+    """Static-embedding embedder (no torch, no GPU).
+
+    The model is loaded lazily on the first :meth:`embed` call so that constructing a
+    :class:`~agentrecall.memory.Memory` in ``embeddings="auto"`` mode is cheap. Raises
+    :class:`~agentrecall.errors.EmbeddingsUnavailable` if ``model2vec`` is not installed.
+    """
+
+    def __init__(self, model: str = DEFAULT_MODEL) -> None:
+        self._model_name = model
+        self._model = None
+        self._dim: int | None = None
+
+    def _ensure_loaded(self) -> None:
+        if self._model is not None:
+            return
+        try:
+            from model2vec import StaticModel
+        except ImportError as exc:  # pragma: no cover - exercised via guarded tests
+            raise EmbeddingsUnavailable(
+                "Semantic search needs the optional 'semantic' extra. "
+                "Install it with:  pip install 'agentrecall[semantic]'"
+            ) from exc
+        self._model = StaticModel.from_pretrained(self._model_name)
+        # model2vec exposes the embedding dimension on the loaded model.
+        self._dim = int(self._model.dim)
+
+    @property
+    def dim(self) -> int:
+        self._ensure_loaded()
+        assert self._dim is not None
+        return self._dim
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        self._ensure_loaded()
+        assert self._model is not None
+        vectors = self._model.encode(list(texts))
+        # model2vec returns a numpy array; normalise to plain Python floats.
+        return [[float(x) for x in row] for row in vectors]
+
+
+def get_default_embedder() -> Embedder | None:
+    """Return a :class:`Model2VecEmbedder` if ``model2vec`` is importable, else ``None``.
+
+    Never raises — this is the probe used by ``embeddings="auto"``.
+    """
+    import importlib.util
+
+    if importlib.util.find_spec("model2vec") is None:
+        return None
+    return Model2VecEmbedder()
+
+
+__all__ = ["Embedder", "Model2VecEmbedder", "get_default_embedder", "DEFAULT_MODEL"]

agentrecall/errors.py

@@ -0,0 +1,36 @@
+"""Exception hierarchy for agentrecall.
+
+All errors raised by the library subclass :class:`AgentRecallError`, so callers can
+``except AgentRecallError`` to catch anything the library throws.
+"""
+
+from __future__ import annotations
+
+
+class AgentRecallError(Exception):
+    """Base class for all agentrecall errors."""
+
+
+class MemoryNotFound(AgentRecallError):
+    """Raised by ``get()`` / ``update()`` / ``delete()`` when the id does not exist."""
+
+    def __init__(self, memory_id: int) -> None:
+        self.memory_id = memory_id
+        super().__init__(f"No memory with id {memory_id!r}")
+
+
+class EmbeddingsUnavailable(AgentRecallError):
+    """Raised when semantic mode is required (``embeddings=True``) but the optional
+    ``[semantic]`` extra (model2vec / sqlite-vec) is not installed or cannot load."""
+
+
+class StoreError(AgentRecallError):
+    """Wraps an unexpected SQLite-level failure."""
+
+
+__all__ = [
+    "AgentRecallError",
+    "MemoryNotFound",
+    "EmbeddingsUnavailable",
+    "StoreError",
+]

agentrecall/mcp_server.py

@@ -0,0 +1,70 @@
+"""Expose a :class:`~agentrecall.memory.Memory` as an MCP server.
+
+This is a drop-in, embeddings-capable alternative to the official memory MCP server
+(which persists to a keyword-only JSONL flat file). Here memories live in a portable
+SQLite file and recall can be hybrid keyword + semantic.
+
+Requires the optional ``mcp`` extra:  ``pip install 'agentrecall[mcp]'``.
+"""
+
+from __future__ import annotations
+
+from .memory import Memory
+
+
+def build_mcp_server(memory: Memory, *, name: str = "agentrecall"):
+    """Return a configured FastMCP server exposing remember/recall/forget tools."""
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError as exc:  # pragma: no cover - exercised only without the extra
+        raise ImportError(
+            "The agentrecall MCP server needs the optional 'mcp' extra. "
+            "Install it with:  pip install 'agentrecall[mcp]'"
+        ) from exc
+
+    server = FastMCP(name)
+
+    @server.tool()
+    def remember(
+        content: str,
+        tags: list[str] | None = None,
+        metadata: dict | None = None,
+        importance: float = 1.0,
+    ) -> dict:
+        """Store a new memory verbatim and return the stored record."""
+        record = memory.add(content, tags=tags, metadata=metadata, importance=importance)
+        return record.to_dict()
+
+    @server.tool()
+    def recall(query: str, k: int = 5, tags: list[str] | None = None) -> list[dict]:
+        """Search stored memories; returns the most relevant first."""
+        return [hit.to_dict() for hit in memory.search(query, k=k, tags=tags)]
+
+    @server.tool()
+    def forget(memory_id: int) -> bool:
+        """Delete a memory by id. Returns True if a row was removed."""
+        return memory.delete(memory_id)
+
+    @server.tool()
+    def list_memories(limit: int = 20) -> list[dict]:
+        """List the most recent memories."""
+        return [record.to_dict() for record in memory.all(limit=limit)]
+
+    @server.tool()
+    def memory_stats() -> dict:
+        """Return counts and the active configuration."""
+        return {
+            "count": memory.count(),
+            "namespace": memory.namespace,
+            "semantic": memory.semantic_enabled,
+        }
+
+    return server
+
+
+def serve(memory: Memory, *, transport: str = "stdio") -> None:
+    """Build and run the MCP server (blocking)."""
+    build_mcp_server(memory).run(transport=transport)
+
+
+__all__ = ["build_mcp_server", "serve"]