memsmith 0.1.0__py3-none-any.whl

memsmith/__init__.py

@@ -0,0 +1,56 @@
+"""Memsmith — Enterprise memory lifecycle management for AI agents."""
+
+from memsmith._types import (
+    Accepted,
+    AuditEntry,
+    Memory,
+    MemoryStatus,
+    PendingConfirmation,
+    ProposalInput,
+    ProposalResult,
+    Rejected,
+    ValidationResult,
+    ValidatorFn,
+    ValidatorSpec,
+)
+from memsmith._errors import (
+    ConfidenceMonotonicityError,
+    InvalidTransitionError,
+    MemsmithError,
+    NotFoundError,
+    ValidationError,
+)
+from memsmith._store import MemoryStore
+from memsmith._validators import (
+    ConfidenceThreshold,
+    SchemaCheck,
+    Validator,
+)
+from memsmith._sqlite import SQLiteBackend
+from memsmith._hooks import HookRegistry, TransitionHandler
+
+__all__ = [
+    "Accepted",
+    "AuditEntry",
+    "ConfidenceMonotonicityError",
+    "ConfidenceThreshold",
+    "HookRegistry",
+    "InvalidTransitionError",
+    "Memory",
+    "MemoryStatus",
+    "MemoryStore",
+    "MemsmithError",
+    "NotFoundError",
+    "PendingConfirmation",
+    "ProposalInput",
+    "ProposalResult",
+    "Rejected",
+    "SchemaCheck",
+    "SQLiteBackend",
+    "TransitionHandler",
+    "ValidationError",
+    "ValidationResult",
+    "Validator",
+    "ValidatorFn",
+    "ValidatorSpec",
+]

memsmith/_backend.py

@@ -0,0 +1,62 @@
+import contextvars
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any, Protocol, runtime_checkable
+
+from memsmith._types import AuditEntry, Memory, MemoryStatus
+
+
+_tx_conn: contextvars.ContextVar = contextvars.ContextVar("_tx_conn")
+
+
+def _get_tx_conn() -> Any:
+    return _tx_conn.get(None)
+
+
+@runtime_checkable
+class StorageBackend(Protocol):
+    async def initialize(self) -> None: ...
+
+    async def close(self) -> None: ...
+
+    @asynccontextmanager
+    async def transaction(self) -> AsyncIterator[None]:
+        yield
+
+    async def insert_memory(self, memory: Memory, /) -> str: ...
+
+    async def get_memory(self, memory_id: str, /) -> Memory | None: ...
+
+    async def update_status(
+        self, memory_id: str, /, new_status: MemoryStatus, **extra: Any
+    ) -> None: ...
+
+    async def update_content(
+        self, memory_id: str, /, new_content: Any, new_hash: str
+    ) -> None: ...
+
+    async def update_confidence(
+        self, memory_id: str, /, new_value: float
+    ) -> None: ...
+
+    async def list_memories(
+        self,
+        status: MemoryStatus | None = None,
+        session_id: str | None = None,
+        field_filters: dict[str, Any] | None = None,
+        limit: int = 50,
+        offset: int = 0,
+        order_by: str = "created_at",
+    ) -> list[Memory]: ...
+
+    async def find_by_hash(
+        self, content_hash: str, session_id: str, /
+    ) -> Memory | None: ...
+
+    async def expire_batch(self) -> int: ...
+
+    async def log_audit(self, entry: AuditEntry, /) -> str: ...
+
+    async def get_audit(
+        self, memory_id: str | None = None, /, limit: int = 50
+    ) -> list[AuditEntry]: ...

memsmith/_errors.py

@@ -0,0 +1,49 @@
+from memsmith._types import MemoryStatus
+
+
+class MemsmithError(Exception):
+    pass
+
+
+class InvalidTransitionError(MemsmithError):
+    def __init__(
+        self,
+        memory_id: str,
+        from_status: MemoryStatus,
+        to_status: MemoryStatus,
+    ) -> None:
+        self.memory_id = memory_id
+        self.from_status = from_status
+        self.to_status = to_status
+        super().__init__(
+            f"Invalid transition: memory {memory_id} "
+            f"cannot go from {from_status.value} to {to_status.value}"
+        )
+
+
+class NotFoundError(MemsmithError):
+    def __init__(self, memory_id: str) -> None:
+        self.memory_id = memory_id
+        super().__init__(f"Memory not found: {memory_id}")
+
+
+class ConfidenceMonotonicityError(MemsmithError):
+    def __init__(self, memory_id: str, current: float, attempted: float) -> None:
+        self.memory_id = memory_id
+        self.current = current
+        self.attempted = attempted
+        super().__init__(
+            f"Confidence must increase monotonically: "
+            f"memory {memory_id} has {current}, attempted {attempted}"
+        )
+
+
+class ValidationError(MemsmithError):
+    def __init__(self, errors: list[str], memory_id: str | None = None) -> None:
+        self.memory_id = memory_id
+        self.errors = errors
+        joined = "; ".join(errors)
+        if memory_id:
+            super().__init__(f"Validation failed for memory {memory_id}: {joined}")
+        else:
+            super().__init__(f"Validation failed: {joined}")

memsmith/_hashing.py

@@ -0,0 +1,15 @@
+import hashlib
+import json
+from typing import Any
+
+
+def compute_content_hash(content: Any) -> str:
+    """SHA-256 of the JSON-serialized content, sorted keys for determinism."""
+    serialized = json.dumps(
+        content,
+        sort_keys=True,
+        ensure_ascii=False,
+        default=str,
+        separators=(",", ":"),
+    )
+    return hashlib.sha256(serialized.encode("utf-8")).hexdigest()

memsmith/_hooks.py

@@ -0,0 +1,36 @@
+import logging
+from collections.abc import Awaitable, Callable
+
+from memsmith._types import MemoryStatus
+
+logger = logging.getLogger("memsmith")
+
+TransitionHandler = Callable[[str, MemoryStatus, MemoryStatus], Awaitable[None]]
+
+
+class HookRegistry:
+    """Ordered list of post-commit transition callbacks. Fire-and-forget errors."""
+
+    def __init__(self) -> None:
+        self._callbacks: list[TransitionHandler] = []
+
+    def register(self, callback: TransitionHandler) -> None:
+        self._callbacks.append(callback)
+
+    async def emit(
+        self,
+        memory_id: str,
+        from_status: MemoryStatus,
+        to_status: MemoryStatus,
+    ) -> None:
+        for cb in self._callbacks:
+            try:
+                await cb(memory_id, from_status, to_status)
+            except Exception:
+                logger.exception(
+                    "Hook %r raised for memory %s transition %s->%s",
+                    cb,
+                    memory_id,
+                    from_status.value,
+                    to_status.value,
+                )

memsmith/_migrations.py

@@ -0,0 +1,73 @@
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+
+@dataclass
+class Migration:
+    version: int
+    description: str
+    sql: str
+
+
+MIGRATIONS: list[Migration] = [
+    Migration(
+        version=1,
+        description="Initial schema: memories and audit_log tables",
+        sql="""
+        CREATE TABLE IF NOT EXISTS memories (
+            id TEXT PRIMARY KEY,
+            content TEXT NOT NULL,
+            session_id TEXT NOT NULL,
+            thread_id TEXT,
+            source TEXT,
+            confidence REAL NOT NULL,
+            content_hash TEXT NOT NULL,
+            status TEXT NOT NULL,
+            depends_on TEXT DEFAULT '[]',
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL,
+            expires_at TEXT,
+            retracted_at TEXT,
+            retraction_reason TEXT
+        );
+        CREATE TABLE IF NOT EXISTS audit_log (
+            id TEXT PRIMARY KEY,
+            memory_id TEXT NOT NULL,
+            action TEXT NOT NULL,
+            from_status TEXT,
+            to_status TEXT,
+            timestamp TEXT NOT NULL,
+            metadata TEXT DEFAULT '{}'
+        );
+        CREATE INDEX IF NOT EXISTS idx_memories_session ON memories(session_id);
+        CREATE INDEX IF NOT EXISTS idx_memories_status ON memories(status);
+        CREATE INDEX IF NOT EXISTS idx_memories_session_status ON memories(session_id, status);
+        CREATE INDEX IF NOT EXISTS idx_memories_created ON memories(created_at);
+        CREATE INDEX IF NOT EXISTS idx_memories_expires ON memories(expires_at);
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_memories_hash_session ON memories(content_hash, session_id)
+            WHERE status IN ('active', 'proposed', 'pending_confirmation');
+        CREATE INDEX IF NOT EXISTS idx_audit_memory ON audit_log(memory_id);
+        """,
+    ),
+]
+
+
+async def run_migrations(conn, backend_type: str) -> None:
+    """Idempotent. Tracks applied versions in _migrations table."""
+    await conn.execute(
+        "CREATE TABLE IF NOT EXISTS _migrations "
+        "(version INTEGER PRIMARY KEY, applied_at TEXT NOT NULL)"
+    )
+    rows = await conn.execute_fetchall(
+        "SELECT version FROM _migrations ORDER BY version"
+    )
+    applied = {row[0] for row in rows}
+
+    for migration in MIGRATIONS:
+        if migration.version not in applied:
+            await conn.executescript(migration.sql)
+            await conn.execute(
+                "INSERT INTO _migrations (version, applied_at) VALUES (?, ?)",
+                (migration.version, datetime.now(timezone.utc).isoformat()),
+            )
+            await conn.execute("COMMIT")

memsmith/_sqlite.py

@@ -0,0 +1,261 @@
+import json
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+from typing import Any
+
+import aiosqlite
+
+from memsmith._backend import _get_tx_conn, _tx_conn
+from memsmith._migrations import run_migrations
+from memsmith._types import AuditEntry, Memory, MemoryStatus
+
+_ORDER_BY_WHITELIST = frozenset(
+    {"created_at", "updated_at", "confidence", "status", "session_id"}
+)
+
+
+class SQLiteBackend:
+    def __init__(self, path: str = ":memory:") -> None:
+        self._path = path
+        self._conn: aiosqlite.Connection | None = None
+
+    def _get_conn(self) -> aiosqlite.Connection:
+        tx_conn = _get_tx_conn()
+        if tx_conn is not None:
+            return tx_conn
+        if self._conn is None:
+            raise RuntimeError("SQLiteBackend not initialized")
+        return self._conn
+
+    @staticmethod
+    def _row_to_memory(row: aiosqlite.Row) -> Memory:
+        return Memory(
+            id=row["id"],
+            content=json.loads(row["content"]),
+            session_id=row["session_id"],
+            thread_id=row["thread_id"],
+            source=row["source"],
+            confidence=row["confidence"],
+            content_hash=row["content_hash"],
+            status=MemoryStatus(row["status"]),
+            depends_on=json.loads(row["depends_on"]),
+            created_at=datetime.fromisoformat(row["created_at"]),
+            updated_at=datetime.fromisoformat(row["updated_at"]),
+            expires_at=datetime.fromisoformat(row["expires_at"]) if row["expires_at"] else None,
+            retracted_at=datetime.fromisoformat(row["retracted_at"]) if row["retracted_at"] else None,
+            retraction_reason=row["retraction_reason"],
+        )
+
+    @staticmethod
+    def _row_to_audit_entry(row: aiosqlite.Row) -> AuditEntry:
+        return AuditEntry(
+            id=row["id"],
+            memory_id=row["memory_id"],
+            action=row["action"],
+            from_status=MemoryStatus(row["from_status"]) if row["from_status"] else None,
+            to_status=MemoryStatus(row["to_status"]) if row["to_status"] else None,
+            timestamp=datetime.fromisoformat(row["timestamp"]),
+            metadata=json.loads(row["metadata"]),
+        )
+
+    async def initialize(self) -> None:
+        self._conn = await aiosqlite.connect(self._path)
+        self._conn.row_factory = aiosqlite.Row
+        await self._conn.execute("PRAGMA journal_mode=WAL")
+        await self._conn.execute("PRAGMA foreign_keys=ON")
+        await run_migrations(self._conn, "sqlite")
+
+    async def close(self) -> None:
+        if self._conn is not None:
+            await self._conn.close()
+            self._conn = None
+
+    @asynccontextmanager
+    async def transaction(self) -> AsyncIterator[None]:
+        token = _tx_conn.set(self._conn)
+        await self._conn.execute("SAVEPOINT memsmith_tx")
+        try:
+            yield
+        except BaseException:
+            await self._conn.execute("ROLLBACK TO memsmith_tx")
+            raise
+        finally:
+            await self._conn.execute("RELEASE memsmith_tx")
+            _tx_conn.reset(token)
+
+    async def insert_memory(self, memory: Memory, /) -> str:
+        conn = self._get_conn()
+        await conn.execute(
+            "INSERT INTO memories "
+            "(id, content, session_id, thread_id, source, confidence, content_hash, "
+            "status, depends_on, created_at, updated_at, expires_at, retracted_at, "
+            "retraction_reason) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            (
+                memory.id,
+                json.dumps(memory.content, ensure_ascii=False, default=str, separators=(",", ":")),
+                memory.session_id,
+                memory.thread_id,
+                memory.source,
+                memory.confidence,
+                memory.content_hash,
+                memory.status.value,
+                json.dumps(memory.depends_on),
+                memory.created_at.isoformat(),
+                memory.updated_at.isoformat(),
+                memory.expires_at.isoformat() if memory.expires_at else None,
+                memory.retracted_at.isoformat() if memory.retracted_at else None,
+                memory.retraction_reason,
+            ),
+        )
+        return memory.id
+
+    async def get_memory(self, memory_id: str, /) -> Memory | None:
+        conn = self._get_conn()
+        cursor = await conn.execute(
+            "SELECT * FROM memories WHERE id = ?", (memory_id,)
+        )
+        row = await cursor.fetchone()
+        return self._row_to_memory(row) if row else None
+
+    async def update_status(
+        self, memory_id: str, /, new_status: MemoryStatus, **extra: Any
+    ) -> None:
+        conn = self._get_conn()
+        now = datetime.now(timezone.utc).isoformat()
+        if extra:
+            set_clause = ", ".join(f"{k} = ?" for k in extra)
+            await conn.execute(
+                f"UPDATE memories SET status = ?, updated_at = ?, {set_clause} WHERE id = ?",
+                (new_status.value, now, *extra.values(), memory_id),
+            )
+        else:
+            await conn.execute(
+                "UPDATE memories SET status = ?, updated_at = ? WHERE id = ?",
+                (new_status.value, now, memory_id),
+            )
+
+    async def update_content(
+        self, memory_id: str, /, new_content: Any, new_hash: str
+    ) -> None:
+        conn = self._get_conn()
+        now = datetime.now(timezone.utc).isoformat()
+        await conn.execute(
+            "UPDATE memories SET content = ?, content_hash = ?, updated_at = ? WHERE id = ?",
+            (
+                json.dumps(new_content, ensure_ascii=False, default=str, separators=(",", ":")),
+                new_hash,
+                now,
+                memory_id,
+            ),
+        )
+
+    async def update_confidence(
+        self, memory_id: str, /, new_value: float
+    ) -> None:
+        conn = self._get_conn()
+        now = datetime.now(timezone.utc).isoformat()
+        await conn.execute(
+            "UPDATE memories SET confidence = ?, updated_at = ? WHERE id = ?",
+            (new_value, now, memory_id),
+        )
+
+    async def list_memories(
+        self,
+        status: MemoryStatus | None = None,
+        session_id: str | None = None,
+        field_filters: dict[str, Any] | None = None,
+        limit: int = 50,
+        offset: int = 0,
+        order_by: str = "created_at",
+    ) -> list[Memory]:
+        conn = self._get_conn()
+        conditions: list[str] = []
+        params: list[Any] = []
+
+        if status is not None:
+            conditions.append("status = ?")
+            params.append(status.value)
+        if session_id is not None:
+            conditions.append("session_id = ?")
+            params.append(session_id)
+        if field_filters:
+            for key, value in field_filters.items():
+                conditions.append(f"{key} = ?")
+                params.append(value)
+
+        where_clause = ""
+        if conditions:
+            where_clause = "WHERE " + " AND ".join(conditions)
+
+        if order_by not in _ORDER_BY_WHITELIST:
+            order_by = "created_at"
+
+        sql = f"SELECT * FROM memories {where_clause} ORDER BY {order_by} LIMIT ? OFFSET ?"
+        params.extend([limit, offset])
+
+        cursor = await conn.execute(sql, tuple(params))
+        rows = await cursor.fetchall()
+        return [self._row_to_memory(row) for row in rows]
+
+    async def find_by_hash(
+        self, content_hash: str, session_id: str, /
+    ) -> Memory | None:
+        conn = self._get_conn()
+        cursor = await conn.execute(
+            "SELECT * FROM memories WHERE content_hash = ? AND session_id = ? "
+            "AND status IN ('active', 'proposed', 'pending_confirmation') LIMIT 1",
+            (content_hash, session_id),
+        )
+        row = await cursor.fetchone()
+        return self._row_to_memory(row) if row else None
+
+    async def expire_batch(self) -> int:
+        conn = self._get_conn()
+        now = datetime.now(timezone.utc).isoformat()
+        cursor = await conn.execute(
+            "UPDATE memories SET status = ?, updated_at = ? "
+            "WHERE status = ? AND expires_at IS NOT NULL AND expires_at <= ?",
+            (
+                MemoryStatus.EXPIRED.value,
+                now,
+                MemoryStatus.ACTIVE.value,
+                now,
+            ),
+        )
+        return cursor.rowcount
+
+    async def log_audit(self, entry: AuditEntry, /) -> str:
+        conn = self._get_conn()
+        await conn.execute(
+            "INSERT INTO audit_log (id, memory_id, action, from_status, to_status, timestamp, metadata) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (
+                entry.id,
+                entry.memory_id,
+                entry.action,
+                entry.from_status.value if entry.from_status else None,
+                entry.to_status.value if entry.to_status else None,
+                entry.timestamp.isoformat(),
+                json.dumps(entry.metadata),
+            ),
+        )
+        return entry.id
+
+    async def get_audit(
+        self, memory_id: str | None = None, /, limit: int = 50
+    ) -> list[AuditEntry]:
+        conn = self._get_conn()
+        if memory_id:
+            cursor = await conn.execute(
+                "SELECT * FROM audit_log WHERE memory_id = ? ORDER BY timestamp DESC LIMIT ?",
+                (memory_id, limit),
+            )
+        else:
+            cursor = await conn.execute(
+                "SELECT * FROM audit_log ORDER BY timestamp DESC LIMIT ?",
+                (limit,),
+            )
+        rows = await cursor.fetchall()
+        return [self._row_to_audit_entry(row) for row in rows]