agentforge-memory-sqlite 0.2.1__py3-none-any.whl

agentforge_memory_sqlite/__init__.py

@@ -0,0 +1,17 @@
+"""AgentForge — SQLite memory + vector drivers.
+
+Implements `MemoryStore` (claim audit log) and `VectorStore` (semantic
+search) over SQLite via `aiosqlite`. Zero external services required.
+
+Per ADR-0014 every code path is async — uses `aiosqlite`, never the
+blocking stdlib `sqlite3`, in agent code paths.
+"""
+
+from __future__ import annotations
+
+from agentforge_memory_sqlite.memory import SqliteMemoryStore
+from agentforge_memory_sqlite.vector import SqliteVectorStore
+
+__version__ = "0.2.1"
+
+__all__ = ["SqliteMemoryStore", "SqliteVectorStore", "__version__"]

agentforge_memory_sqlite/_migrator.py

@@ -0,0 +1,144 @@
+"""`SqliteMigrator` — SQLite-side implementation of the feat-024
+:class:`agentforge_core.Migrator` Protocol.
+
+Migrations ship at
+``agentforge_memory_sqlite/migrations/NNNN_<name>.sql``. The
+migrator runs each pending migration via
+:meth:`aiosqlite.Connection.executescript` so multi-statement files
+work as written. Each migration is wrapped in an explicit
+transaction so a partial failure rolls back cleanly.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import aiosqlite
+from agentforge_core.contracts.migrator import (
+    Migration,
+    MigrationChecksumError,
+    MigrationStatus,
+)
+from agentforge_core.migrations import discover_migrations, render_migration_up
+
+
+def _default_migrations_path() -> Path:
+    return Path(__file__).parent / "migrations"
+
+
+class SqliteMigrator:
+    """SQLite implementation of :class:`agentforge_core.Migrator`."""
+
+    def __init__(
+        self,
+        connection: aiosqlite.Connection,
+        *,
+        variables: dict[str, str] | None = None,
+        migrations_path: Path | None = None,
+    ) -> None:
+        self._db = connection
+        self._path = migrations_path or _default_migrations_path()
+        self._variables = variables
+        self._migrations: list[Migration] = discover_migrations(self._path, suffix="sql")
+
+    @property
+    def migrations(self) -> list[Migration]:
+        return list(self._migrations)
+
+    async def current_version(self) -> str | None:
+        if not await self._tracking_table_exists():
+            return None
+        async with self._db.execute("SELECT MAX(id) AS latest FROM agentforge_migrations") as cur:
+            row = await cur.fetchone()
+        if row is None or row["latest"] is None:
+            return None
+        return str(row["latest"])
+
+    async def status(self) -> list[MigrationStatus]:
+        applied = await self._fetch_applied()
+        out: list[MigrationStatus] = []
+        for migration in self._migrations:
+            record = applied.get(migration.id)
+            if record is None:
+                out.append(
+                    MigrationStatus(
+                        migration=migration,
+                        applied=False,
+                        applied_at=None,
+                        checksum_match=False,
+                    )
+                )
+                continue
+            out.append(
+                MigrationStatus(
+                    migration=migration,
+                    applied=True,
+                    applied_at=_parse_iso(record["applied_at"]),
+                    checksum_match=record["checksum"] == migration.checksum,
+                )
+            )
+        return out
+
+    async def apply_pending(self) -> list[Migration]:
+        applied = await self._fetch_applied()
+
+        for migration in self._migrations:
+            record = applied.get(migration.id)
+            if record is not None and record["checksum"] != migration.checksum:
+                msg = (
+                    f"SQLite migration {migration.id}_{migration.name} "
+                    f"checksum drift: recorded {record['checksum']!r} but "
+                    f"file is now {migration.checksum!r}."
+                )
+                raise MigrationChecksumError(msg)
+
+        new_applied: list[Migration] = []
+        for migration in self._migrations:
+            if migration.id in applied:
+                continue
+            # `executescript` handles multi-statement migrations.
+            # It implicitly commits, so we explicitly BEGIN before
+            # and rely on the script's final state for the row write.
+            rendered = render_migration_up(migration.up, self._variables)
+            await self._db.executescript(rendered)
+            await self._db.execute(
+                "INSERT INTO agentforge_migrations(id, name, checksum) VALUES (?, ?, ?)",
+                (migration.id, migration.name, migration.checksum),
+            )
+            await self._db.commit()
+            new_applied.append(migration)
+        return new_applied
+
+    async def _tracking_table_exists(self) -> bool:
+        async with self._db.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name='agentforge_migrations'"
+        ) as cur:
+            row = await cur.fetchone()
+        return row is not None
+
+    async def _fetch_applied(self) -> dict[str, dict[str, Any]]:
+        if not await self._tracking_table_exists():
+            return {}
+        async with self._db.execute(
+            "SELECT id, name, checksum, applied_at FROM agentforge_migrations"
+        ) as cur:
+            rows = await cur.fetchall()
+        return {
+            str(row["id"]): {
+                "name": row["name"],
+                "checksum": row["checksum"],
+                "applied_at": row["applied_at"],
+            }
+            for row in rows
+        }
+
+
+def _parse_iso(value: Any) -> datetime | None:
+    if not value:
+        return None
+    try:
+        return datetime.fromisoformat(str(value))
+    except ValueError:
+        return None

agentforge_memory_sqlite/memory.py

@@ -0,0 +1,244 @@
+"""`SqliteMemoryStore` — `MemoryStore` over SQLite via aiosqlite.
+
+Single-table schema: every claim is stored as one row keyed by `id`
+with project / agent / category / run_id / supersedes columns and
+the JSON payload as a TEXT blob. Queries hit composite indices on
+the common filter combinations.
+
+Schema is created on first connect via `CREATE TABLE IF NOT EXISTS`.
+No migrations in v0.1 — the table shape is fixed.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from datetime import datetime
+from pathlib import Path
+from types import TracebackType
+from typing import Any
+
+import aiosqlite
+from agentforge_core.contracts.memory import MemoryStore
+from agentforge_core.production.exceptions import ModuleError
+from agentforge_core.values.claim import Claim
+
+from agentforge_memory_sqlite._migrator import SqliteMigrator
+
+
+class SqliteMemoryStore(MemoryStore):
+    """Persistent `MemoryStore` backed by a single SQLite file.
+
+    Use `from_path(path)` for ergonomic construction; the bare
+    constructor accepts an already-opened `aiosqlite.Connection` for
+    callers who manage the connection themselves.
+    """
+
+    def __init__(self, *, connection: aiosqlite.Connection) -> None:
+        self._db = connection
+
+    # ------------------------------------------------------------------
+    # Construction / lifecycle
+    # ------------------------------------------------------------------
+
+    @classmethod
+    async def from_path(cls, path: str | Path) -> SqliteMemoryStore:
+        """Open or create a SQLite database at `path` and return a store.
+
+        `path` may be `":memory:"` for an ephemeral in-process database,
+        or a filesystem path (the parent directory must exist).
+        """
+        connection = await aiosqlite.connect(str(path))
+        connection.row_factory = aiosqlite.Row
+        # feat-024: schema bootstrap is now versioned via the
+        # migration framework. Idempotent: re-opening an existing
+        # database is a no-op after migrations are applied.
+        await SqliteMigrator(connection).apply_pending()
+        return cls(connection=connection)
+
+    def migrator(self) -> SqliteMigrator:
+        """Return a `SqliteMigrator` configured against the
+        package's bundled migrations directory (feat-024)."""
+        return SqliteMigrator(self._db)
+
+    async def init_schema(self) -> None:
+        """Apply every bundled migration (idempotent). Opt-in.
+
+        Delegates to the feat-024 migration framework. `from_path`
+        already calls this implicitly; standalone callers (or
+        tests that construct the store from a raw connection) can
+        invoke it directly.
+        """
+        await self.migrator().apply_pending()
+
+    async def __aenter__(self) -> SqliteMemoryStore:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._db.close()
+
+    # ------------------------------------------------------------------
+    # MemoryStore contract
+    # ------------------------------------------------------------------
+
+    async def put(self, claim: Claim) -> str:
+        await self._db.execute(
+            """INSERT OR REPLACE INTO claims
+               (id, project, agent, run_id, category, payload, supersedes, created_at)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                claim.id,
+                claim.project,
+                claim.agent,
+                claim.run_id,
+                claim.category,
+                json.dumps(claim.payload),
+                claim.supersedes,
+                claim.created_at.isoformat(),
+            ),
+        )
+        await self._db.commit()
+        return claim.id
+
+    async def get(self, claim_id: str) -> Claim | None:
+        async with self._db.execute(
+            "SELECT * FROM claims WHERE id = ?",
+            (claim_id,),
+        ) as cur:
+            row = await cur.fetchone()
+        if row is None:
+            return None
+        return _row_to_claim(row)
+
+    async def query(
+        self,
+        *,
+        project: str | None = None,
+        agent: str | None = None,
+        category: str | None = None,
+        run_id: str | None = None,
+        limit: int = 100,
+    ) -> list[Claim]:
+        sql, params = _build_filter_sql(project, agent, category, run_id, limit)
+        async with self._db.execute(sql, params) as cur:
+            rows = await cur.fetchall()
+        return [_row_to_claim(row) for row in rows]
+
+    async def supersede(self, old_id: str, new_claim: Claim) -> str:
+        existing = await self.get(old_id)
+        if existing is None:
+            raise ModuleError(f"Cannot supersede unknown claim id: {old_id!r}")
+        if new_claim.supersedes is None:
+            new_claim = new_claim.model_copy(update={"supersedes": old_id})
+        elif new_claim.supersedes != old_id:
+            raise ModuleError(
+                f"new_claim.supersedes={new_claim.supersedes!r} does not match old_id={old_id!r}"
+            )
+        return await self.put(new_claim)
+
+    def stream(
+        self,
+        *,
+        project: str | None = None,
+        agent: str | None = None,
+        category: str | None = None,
+        run_id: str | None = None,
+    ) -> AsyncIterator[Claim]:
+        sql, params = _build_filter_sql(project, agent, category, run_id, limit=None)
+
+        async def _agen() -> AsyncIterator[Claim]:
+            async with self._db.execute(sql, params) as cur:
+                async for row in cur:
+                    yield _row_to_claim(row)
+
+        return _agen()
+
+    async def delete(
+        self,
+        *,
+        run_id: str | None = None,
+        older_than: datetime | None = None,
+        category: str | None = None,
+    ) -> int:
+        if run_id is None and older_than is None and category is None:
+            raise ModuleError(
+                "delete() requires at least one filter; refusing to wipe every claim."
+            )
+        where: list[str] = []
+        params: list[Any] = []
+        if run_id is not None:
+            where.append("run_id = ?")
+            params.append(run_id)
+        if category is not None:
+            where.append("category = ?")
+            params.append(category)
+        if older_than is not None:
+            where.append("created_at < ?")
+            params.append(older_than.isoformat())
+        sql = "DELETE FROM claims WHERE " + " AND ".join(where)  # noqa: S608  # nosec B608
+        cur = await self._db.execute(sql, tuple(params))
+        await self._db.commit()
+        return cur.rowcount or 0
+
+
+# ----------------------------------------------------------------------
+# Helpers
+# ----------------------------------------------------------------------
+
+
+def _row_to_claim(row: Any) -> Claim:
+    """Convert an `aiosqlite.Row` into a `Claim`."""
+    return Claim(
+        id=row["id"],
+        project=row["project"],
+        agent=row["agent"],
+        run_id=row["run_id"],
+        category=row["category"],
+        payload=json.loads(row["payload"]),
+        supersedes=row["supersedes"],
+        created_at=datetime.fromisoformat(row["created_at"]),
+    )
+
+
+def _build_filter_sql(
+    project: str | None,
+    agent: str | None,
+    category: str | None,
+    run_id: str | None,
+    limit: int | None,
+) -> tuple[str, tuple[Any, ...]]:
+    """Compose a SELECT with conjunctive filters and an optional LIMIT."""
+    where: list[str] = []
+    params: list[Any] = []
+    if project is not None:
+        where.append("project = ?")
+        params.append(project)
+    if agent is not None:
+        where.append("agent = ?")
+        params.append(agent)
+    if category is not None:
+        where.append("category = ?")
+        params.append(category)
+    if run_id is not None:
+        where.append("run_id = ?")
+        params.append(run_id)
+
+    sql = "SELECT * FROM claims"
+    if where:
+        sql += " WHERE " + " AND ".join(where)
+    sql += " ORDER BY created_at"
+    if limit is not None:
+        sql += " LIMIT ?"
+        params.append(limit)
+    return sql, tuple(params)
+
+
+__all__ = ["SqliteMemoryStore"]

agentforge_memory_sqlite/migrations/0000_migrations_table.sql

@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS agentforge_migrations (
+    id          TEXT PRIMARY KEY,
+    name        TEXT NOT NULL,
+    checksum    TEXT NOT NULL,
+    applied_at  TEXT NOT NULL DEFAULT (datetime('now'))
+);

agentforge_memory_sqlite/migrations/0001_initial.sql

@@ -0,0 +1,27 @@
+CREATE TABLE IF NOT EXISTS claims (
+    id          TEXT PRIMARY KEY,
+    project     TEXT NOT NULL,
+    agent       TEXT NOT NULL,
+    run_id      TEXT NOT NULL,
+    category    TEXT NOT NULL,
+    payload     TEXT NOT NULL,
+    supersedes  TEXT,
+    created_at  TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_claims_project_agent
+    ON claims(project, agent);
+CREATE INDEX IF NOT EXISTS idx_claims_run_id
+    ON claims(run_id);
+CREATE INDEX IF NOT EXISTS idx_claims_category
+    ON claims(category);
+
+CREATE TABLE IF NOT EXISTS vectors (
+    id          TEXT PRIMARY KEY,
+    vector      BLOB NOT NULL,
+    text        TEXT NOT NULL,
+    metadata    TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS vector_meta (
+    key         TEXT PRIMARY KEY,
+    value       TEXT NOT NULL
+);

agentforge_memory_sqlite/migrations/0002_fts5.sql

@@ -0,0 +1,18 @@
+CREATE VIRTUAL TABLE IF NOT EXISTS vectors_fts USING fts5(
+    text,
+    content='vectors',
+    content_rowid='rowid',
+    tokenize='unicode61'
+);
+CREATE TRIGGER IF NOT EXISTS vectors_ai AFTER INSERT ON vectors BEGIN
+    INSERT INTO vectors_fts(rowid, text) VALUES (new.rowid, new.text);
+END;
+CREATE TRIGGER IF NOT EXISTS vectors_ad AFTER DELETE ON vectors BEGIN
+    INSERT INTO vectors_fts(vectors_fts, rowid, text)
+        VALUES ('delete', old.rowid, old.text);
+END;
+CREATE TRIGGER IF NOT EXISTS vectors_au AFTER UPDATE ON vectors BEGIN
+    INSERT INTO vectors_fts(vectors_fts, rowid, text)
+        VALUES ('delete', old.rowid, old.text);
+    INSERT INTO vectors_fts(rowid, text) VALUES (new.rowid, new.text);
+END;

agentforge_memory_sqlite/vector.py

@@ -0,0 +1,257 @@
+"""`SqliteVectorStore` — `VectorStore` over SQLite via aiosqlite.
+
+Vectors are stored as fixed-width BLOBs (8 bytes per float64, packed
+big-endian). On search the entire table is loaded and cosine
+similarity is computed in Python — O(N) per query. Fine for
+~10k vectors; v0.2 will add an opt-in `sqlite-vec` extension path.
+
+Schema is created on first connect via `CREATE TABLE IF NOT EXISTS`
+and `dimensions` are pinned per database. Re-opening with a
+different dimensions value raises at construction.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import struct
+from pathlib import Path
+from types import TracebackType
+from typing import Any
+
+import aiosqlite
+from agentforge_core.contracts.vector_store import VectorStore
+from agentforge_core.values.vector import VectorItem, VectorMatch
+
+from agentforge_memory_sqlite._migrator import SqliteMigrator
+
+
+class SqliteVectorStore(VectorStore):
+    """Persistent `VectorStore` backed by a SQLite file.
+
+    Use `from_path(path, dimensions)` for ergonomic construction. The
+    bare constructor accepts an opened connection plus dimensions for
+    callers who manage their own connection.
+    """
+
+    def __init__(self, *, connection: aiosqlite.Connection, dimensions: int) -> None:
+        if dimensions < 1:
+            raise ValueError(f"dimensions must be >= 1, got {dimensions}")
+        self._db = connection
+        self._dim = dimensions
+
+    @classmethod
+    async def from_path(cls, path: str | Path, *, dimensions: int) -> SqliteVectorStore:
+        """Open or create a vector store at `path` with `dimensions`.
+
+        If the file already contains a vector index with a different
+        dimension, raises `ValueError` — dimensions are pinned per
+        database to prevent silent corruption.
+        """
+        if dimensions < 1:
+            raise ValueError(f"dimensions must be >= 1, got {dimensions}")
+        connection = await aiosqlite.connect(str(path))
+        connection.row_factory = aiosqlite.Row
+        # feat-024: schema bootstrap via the migration framework.
+        await SqliteMigrator(connection).apply_pending()
+        # Pin dimensions on first use; verify on re-open.
+        async with connection.execute(
+            "SELECT value FROM vector_meta WHERE key = 'dimensions'"
+        ) as cur:
+            existing = await cur.fetchone()
+        if existing is None:
+            await connection.execute(
+                "INSERT INTO vector_meta(key, value) VALUES ('dimensions', ?)",
+                (str(dimensions),),
+            )
+            await connection.commit()
+        else:
+            stored = int(existing["value"])
+            if stored != dimensions:
+                await connection.close()
+                raise ValueError(
+                    f"vector store at {path!s} has dimensions={stored} "
+                    f"but caller asked for dimensions={dimensions}"
+                )
+        return cls(connection=connection, dimensions=dimensions)
+
+    async def __aenter__(self) -> SqliteVectorStore:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    def dimensions(self) -> int:
+        return self._dim
+
+    def migrator(self) -> SqliteMigrator:
+        """Return a `SqliteMigrator` configured against the
+        package's bundled migrations directory (feat-024)."""
+        return SqliteMigrator(self._db)
+
+    async def upsert(self, items: list[VectorItem]) -> None:
+        rows: list[tuple[str, bytes, str, str]] = []
+        for item in items:
+            if len(item.vector) != self._dim:
+                raise ValueError(
+                    f"vector for id={item.id!r} has length {len(item.vector)} "
+                    f"but store dimensions={self._dim}"
+                )
+            normalised = _l2_normalise(item.vector)
+            rows.append(
+                (
+                    item.id,
+                    _pack_vector(normalised),
+                    item.text,
+                    json.dumps(item.metadata),
+                )
+            )
+        await self._db.executemany(
+            "INSERT OR REPLACE INTO vectors(id, vector, text, metadata) VALUES (?, ?, ?, ?)",
+            rows,
+        )
+        await self._db.commit()
+
+    async def search(
+        self,
+        query_vector: tuple[float, ...],
+        *,
+        limit: int = 5,
+        filter_metadata: dict[str, Any] | None = None,
+    ) -> list[VectorMatch]:
+        if limit < 1:
+            raise ValueError(f"limit must be >= 1, got {limit}")
+        if len(query_vector) != self._dim:
+            raise ValueError(
+                f"query vector has length {len(query_vector)} but store dimensions={self._dim}"
+            )
+
+        query = _l2_normalise(query_vector)
+        scored: list[tuple[float, str, str, dict[str, Any]]] = []
+        async with self._db.execute("SELECT * FROM vectors") as cur:
+            async for row in cur:
+                metadata = json.loads(row["metadata"])
+                if filter_metadata is not None and not _matches_filter(metadata, filter_metadata):
+                    continue
+                vec = _unpack_vector(row["vector"], self._dim)
+                similarity = sum(a * b for a, b in zip(query, vec, strict=True))
+                clamped = max(0.0, min(1.0, similarity))
+                scored.append((clamped, row["id"], row["text"], metadata))
+
+        scored.sort(key=lambda r: r[0], reverse=True)
+        return [
+            VectorMatch(id=item_id, text=text, metadata=meta, score=score)
+            for score, item_id, text, meta in scored[:limit]
+        ]
+
+    async def lexical_search(
+        self,
+        query: str,
+        *,
+        limit: int = 5,
+        filter_metadata: dict[str, Any] | None = None,
+    ) -> list[VectorMatch]:
+        if limit < 1:
+            raise ValueError(f"limit must be >= 1, got {limit}")
+        escaped = _escape_fts_query(query)
+        if not escaped:
+            return []
+        # Over-fetch when metadata filter is set so post-filter has
+        # room to work; the in-memory store uses the same pattern.
+        over_fetch = limit if filter_metadata is None else limit * 4
+        async with self._db.execute(
+            "SELECT v.id, v.text, v.metadata, "
+            "       -bm25(vectors_fts) AS raw "
+            "  FROM vectors_fts "
+            "  JOIN vectors v ON v.rowid = vectors_fts.rowid "
+            " WHERE vectors_fts MATCH ? "
+            " ORDER BY raw DESC "
+            " LIMIT ?",
+            (escaped, max(over_fetch, 1)),
+        ) as cur:
+            rows = list(await cur.fetchall())
+        if not rows:
+            return []
+
+        top_raw = float(rows[0]["raw"])
+        matches: list[VectorMatch] = []
+        for row in rows:
+            metadata = json.loads(row["metadata"])
+            if filter_metadata is not None and not _matches_filter(metadata, filter_metadata):
+                continue
+            raw = float(row["raw"])
+            score = raw / top_raw if top_raw > 0 else 0.0
+            matches.append(
+                VectorMatch(
+                    id=str(row["id"]),
+                    text=str(row["text"]),
+                    metadata=metadata,
+                    score=score,
+                )
+            )
+            if len(matches) >= limit:
+                break
+        return matches
+
+    def capabilities(self) -> set[str]:
+        """SQLite ships native FTS5; hybrid_search is always available
+        once the schema is set up in `from_path()`."""
+        return {"hybrid_search"}
+
+    async def delete(self, ids: list[str]) -> int:
+        if not ids:
+            return 0
+        # `placeholders` is a string of `?` characters, never user
+        # input — `tuple(ids)` is the parametrised payload.
+        placeholders = ",".join("?" for _ in ids)
+        sql = f"DELETE FROM vectors WHERE id IN ({placeholders})"  # noqa: S608  # nosec B608
+        async with self._db.execute(sql, tuple(ids)) as cur:
+            removed = cur.rowcount
+        await self._db.commit()
+        # rowcount is -1 when undefined; coerce to 0 for safety.
+        return max(0, removed)
+
+    async def close(self) -> None:
+        await self._db.close()
+
+
+# ----------------------------------------------------------------------
+# Helpers
+# ----------------------------------------------------------------------
+
+
+def _pack_vector(vector: tuple[float, ...]) -> bytes:
+    """Pack a float tuple into a fixed-width float64 BLOB."""
+    return struct.pack(f"<{len(vector)}d", *vector)
+
+
+def _unpack_vector(blob: bytes, dim: int) -> tuple[float, ...]:
+    """Reverse of `_pack_vector`."""
+    return struct.unpack(f"<{dim}d", blob)
+
+
+def _l2_normalise(vector: tuple[float, ...]) -> tuple[float, ...]:
+    norm = math.sqrt(sum(x * x for x in vector))
+    if norm == 0.0:
+        return vector
+    return tuple(x / norm for x in vector)
+
+
+def _matches_filter(metadata: dict[str, Any], filter_md: dict[str, Any]) -> bool:
+    return all(metadata.get(k) == v for k, v in filter_md.items())
+
+
+def _escape_fts_query(query: str) -> str:
+    """Wrap every term in double-quotes so user input that contains
+    FTS5 special syntax (``AND`` / ``OR`` / ``*`` / parens / colons)
+    is treated literally. Empty input yields an empty string."""
+    terms = ['"' + term.replace('"', '""') + '"' for term in query.split() if term]
+    return " ".join(terms)
+
+
+__all__ = ["SqliteVectorStore"]

agentforge_memory_sqlite-0.2.1.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: agentforge-memory-sqlite
+Version: 0.2.1
+Summary: SQLite-backed MemoryStore and VectorStore 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,memory,rag,sqlite,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.1
+Requires-Dist: aiosqlite>=0.20
+Description-Content-Type: text/markdown
+
+# agentforge-memory-sqlite
+
+SQLite-backed `MemoryStore` and `VectorStore` for [AgentForge](https://github.com/Scaffoldic/agentforge-py).
+
+Zero external services required — the database lives in a single file
+(or `:memory:` for tests). Suitable for development, single-host
+deployments, and small-to-medium RAG corpora (~10k vectors).
+
+## Install
+
+```bash
+uv add agentforge-memory-sqlite
+```
+
+## Usage
+
+```python
+from agentforge_memory_sqlite import SqliteMemoryStore, SqliteVectorStore
+
+# Claim audit log
+async with SqliteMemoryStore.from_path("agent.db") as memory:
+    await memory.put(claim)
+
+# Semantic search
+async with SqliteVectorStore.from_path("agent.db", dimensions=1024) as store:
+    await store.upsert(items)
+    matches = await store.search(query_vector, limit=5)
+```
+
+Both classes pass `agentforge_core.testing.run_memory_conformance` /
+`run_vector_conformance` so they're drop-in replacements for the
+in-memory defaults.
+
+## Performance
+
+`SqliteVectorStore` does brute-force cosine search in Python: O(N) per
+query. Fine for ~10k vectors; sluggish past that. v0.2 will add an
+opt-in `sqlite-vec` extension path declared via the `"native_ann"`
+capability flag.

agentforge_memory_sqlite-0.2.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+agentforge_memory_sqlite/__init__.py,sha256=4JIJYH0d-n1cmqRG04dcORbrkCGIvoI_8tmzxwPEwQ0,568
+agentforge_memory_sqlite/_migrator.py,sha256=rRPCPnFFmzVRJfthq3glh3x6kWAD4wk5R96Q2PqF5Us,5076
+agentforge_memory_sqlite/memory.py,sha256=30d_Q2PU4tM2NVjAlD9-BVWbWdu5P6-oAzGA_khcfh0,8262
+agentforge_memory_sqlite/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agentforge_memory_sqlite/vector.py,sha256=v0GZmIBYgKMobizausF91TieoLJ60ohA3CM2l6ei6AE,9532
+agentforge_memory_sqlite/migrations/0000_migrations_table.sql,sha256=Hj8lxWPizGOTsAQloRrmKoDHyCkechdHfOcU3FZlDS0,206
+agentforge_memory_sqlite/migrations/0001_initial.sql,sha256=0GRCe90lRCkgomALxUpqbUsckpAPJU8vGacknMgvhQI,778
+agentforge_memory_sqlite/migrations/0002_fts5.sql,sha256=b27HLnhAoDfdQvxVOoc-fvroqAdGbx-RoavaVK0nJTM,718
+agentforge_memory_sqlite-0.2.1.dist-info/METADATA,sha256=6UC-lz8XeQTHeFjFgbHGfoG1iQreS29cP7fbNbyb3zw,2330
+agentforge_memory_sqlite-0.2.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+agentforge_memory_sqlite-0.2.1.dist-info/entry_points.txt,sha256=_KNwjwkvm11_3J9_W0X2_d-VTnz17LEMBVR8rKds9JM,166
+agentforge_memory_sqlite-0.2.1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+agentforge_memory_sqlite-0.2.1.dist-info/RECORD,,

agentforge_memory_sqlite-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agentforge_memory_sqlite-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[agentforge.memory]
+sqlite = agentforge_memory_sqlite.memory:SqliteMemoryStore
+
+[agentforge.vector_stores]
+sqlite = agentforge_memory_sqlite.vector:SqliteVectorStore

agentforge_memory_sqlite-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.