axor-memory-sqlite 0.1.0__py3-none-any.whl

axor_memory_sqlite/__init__.py

@@ -0,0 +1,5 @@
+"""axor-memory-sqlite — SQLite MemoryProvider for axor-core."""
+from axor_memory_sqlite.provider import SQLiteMemoryProvider
+
+__version__ = "0.1.0"
+__all__ = ["SQLiteMemoryProvider"]

axor_memory_sqlite/provider.py

@@ -0,0 +1,278 @@
+from __future__ import annotations
+
+"""
+SQLite-backed MemoryProvider for axor-core.
+
+Zero external dependencies — uses Python's built-in sqlite3.
+Thread-safe via asyncio.Lock + aiosqlite pattern (runs in thread pool).
+
+Schema:
+
+    CREATE TABLE memory_fragments (
+        namespace   TEXT NOT NULL,
+        key         TEXT NOT NULL,
+        content     TEXT NOT NULL,
+        value       TEXT NOT NULL DEFAULT 'working',
+        token_count INTEGER NOT NULL DEFAULT 0,
+        tags        TEXT NOT NULL DEFAULT '[]',   -- JSON array
+        created_at  TEXT NOT NULL,
+        accessed_at TEXT NOT NULL,
+        metadata    TEXT NOT NULL DEFAULT '{}',   -- JSON object
+        PRIMARY KEY (namespace, key)
+    );
+"""
+
+import asyncio
+import json
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from axor_core.contracts.memory import (
+    MemoryFragment,
+    MemoryProvider,
+    MemoryQuery,
+    FragmentValue,
+)
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS memory_fragments (
+    namespace    TEXT    NOT NULL,
+    key          TEXT    NOT NULL,
+    content      TEXT    NOT NULL,
+    value        TEXT    NOT NULL DEFAULT 'working',
+    token_count  INTEGER NOT NULL DEFAULT 0,
+    tags         TEXT    NOT NULL DEFAULT '[]',
+    created_at   TEXT    NOT NULL,
+    accessed_at  TEXT    NOT NULL,
+    metadata     TEXT    NOT NULL DEFAULT '{}',
+    PRIMARY KEY (namespace, key)
+);
+
+CREATE INDEX IF NOT EXISTS idx_namespace ON memory_fragments(namespace);
+CREATE INDEX IF NOT EXISTS idx_value     ON memory_fragments(value);
+CREATE INDEX IF NOT EXISTS idx_accessed  ON memory_fragments(accessed_at);
+"""
+
+_NOW = lambda: datetime.now(timezone.utc).isoformat()
+
+
+def _row_to_fragment(row: tuple) -> MemoryFragment:
+    ns, key, content, value, token_count, tags_json, created_at, accessed_at, meta_json = row
+    return MemoryFragment(
+        namespace=ns,
+        key=key,
+        content=content,
+        value=FragmentValue(value),
+        token_count=token_count,
+        tags=json.loads(tags_json),
+        created_at=datetime.fromisoformat(created_at),
+        accessed_at=datetime.fromisoformat(accessed_at),
+        metadata=json.loads(meta_json),
+    )
+
+
+class SQLiteMemoryProvider(MemoryProvider):
+    """
+    SQLite-backed MemoryProvider.
+
+    All I/O runs in a thread pool via asyncio.to_thread()
+    so async callers are never blocked.
+
+    Usage:
+
+        from axor_memory_sqlite import SQLiteMemoryProvider
+        from axor_core import GovernedSession, AgentDefinition
+
+        provider = SQLiteMemoryProvider("~/.axor/memory.db")
+
+        session = GovernedSession(
+            executor=...,
+            capability_executor=...,
+            agent_def=AgentDefinition(
+                name="my-agent",
+                memory_namespaces=("my-agent", "shared"),
+            ),
+            memory_provider=provider,
+        )
+
+        # save memory after a session
+        await session.save_memory(
+            key="last_project",
+            content="Working on axor federation support",
+            value=FragmentValue.WORKING,
+        )
+    """
+
+    def __init__(self, db_path: str | Path = ":memory:") -> None:
+        self._db_path = str(Path(db_path).expanduser()) if db_path != ":memory:" else ":memory:"
+        self._lock    = asyncio.Lock()
+        self._conn: sqlite3.Connection | None = None
+
+    def _open(self) -> sqlite3.Connection:
+        if self._conn is None:
+            self._conn = sqlite3.connect(self._db_path, check_same_thread=False)
+            self._conn.row_factory = sqlite3.Row
+            self._conn.executescript(_SCHEMA)
+            self._conn.commit()
+        return self._conn
+
+    async def _run(self, fn):
+        """Run a blocking DB call in thread pool."""
+        return await asyncio.to_thread(fn)
+
+    # ── MemoryProvider interface ────────────────────────────────────────────────
+
+    async def load(self, query: MemoryQuery) -> list[MemoryFragment]:
+        def _load():
+            conn = self._open()
+            parts: list[str] = []
+            params: list[Any] = []
+
+            if query.namespaces:
+                placeholders = ",".join("?" * len(query.namespaces))
+                parts.append(f"namespace IN ({placeholders})")
+                params.extend(query.namespaces)
+
+            if query.values:
+                placeholders = ",".join("?" * len(query.values))
+                parts.append(f"value IN ({placeholders})")
+                params.extend(v.value for v in query.values)
+
+            where = ("WHERE " + " AND ".join(parts)) if parts else ""
+            sql = f"""
+                SELECT namespace, key, content, value, token_count, tags,
+                       created_at, accessed_at, metadata
+                FROM memory_fragments
+                {where}
+                ORDER BY
+                    CASE value
+                        WHEN 'pinned'    THEN 0
+                        WHEN 'knowledge' THEN 1
+                        WHEN 'working'   THEN 2
+                        WHEN 'ephemeral' THEN 3
+                    END,
+                    accessed_at DESC
+                LIMIT ?
+            """
+            params.append(query.max_results)
+            rows = conn.execute(sql, params).fetchall()
+            return [_row_to_fragment(tuple(r)) for r in rows]
+
+        try:
+            async with self._lock:
+                return await self._run(_load)
+        except Exception:
+            return []
+
+    async def save(self, fragments: list[MemoryFragment]) -> None:
+        def _save():
+            conn = self._open()
+            now  = _NOW()
+            rows = [
+                (
+                    f.namespace,
+                    f.key,
+                    f.content,
+                    f.value.value,
+                    f.token_count or len(f.content) // 4,
+                    json.dumps(f.tags),
+                    f.created_at.isoformat() if f.created_at else now,
+                    now,
+                    json.dumps(f.metadata),
+                )
+                for f in fragments
+            ]
+            conn.executemany("""
+                INSERT INTO memory_fragments
+                    (namespace, key, content, value, token_count, tags,
+                     created_at, accessed_at, metadata)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT(namespace, key) DO UPDATE SET
+                    content     = excluded.content,
+                    value       = excluded.value,
+                    token_count = excluded.token_count,
+                    tags        = excluded.tags,
+                    accessed_at = excluded.accessed_at,
+                    metadata    = excluded.metadata
+            """, rows)
+            conn.commit()
+
+        try:
+            async with self._lock:
+                await self._run(_save)
+        except Exception:
+            pass
+
+    async def delete(self, namespace: str, keys: list[str]) -> int:
+        def _delete():
+            conn = self._open()
+            placeholders = ",".join("?" * len(keys))
+            cur = conn.execute(
+                f"DELETE FROM memory_fragments WHERE namespace=? AND key IN ({placeholders})",
+                [namespace, *keys],
+            )
+            conn.commit()
+            return cur.rowcount
+
+        try:
+            async with self._lock:
+                return await self._run(_delete)
+        except Exception:
+            return 0
+
+    async def evict(
+        self,
+        namespace: str,
+        values: tuple[FragmentValue, ...] = (FragmentValue.EPHEMERAL,),
+        max_age_seconds: int | None = None,
+    ) -> int:
+        def _evict():
+            conn = self._open()
+            parts: list[str] = ["namespace = ?"]
+            params: list[Any] = [namespace]
+
+            if values:
+                placeholders = ",".join("?" * len(values))
+                parts.append(f"value IN ({placeholders})")
+                params.extend(v.value for v in values)
+
+            if max_age_seconds is not None:
+                parts.append(
+                    "accessed_at < datetime('now', ?)"
+                )
+                params.append(f"-{max_age_seconds} seconds")
+
+            where = " AND ".join(parts)
+            cur = conn.execute(
+                f"DELETE FROM memory_fragments WHERE {where}",
+                params,
+            )
+            conn.commit()
+            return cur.rowcount
+
+        try:
+            async with self._lock:
+                return await self._run(_evict)
+        except Exception:
+            return 0
+
+    async def namespaces(self) -> list[str]:
+        def _ns():
+            conn = self._open()
+            rows = conn.execute(
+                "SELECT DISTINCT namespace FROM memory_fragments ORDER BY namespace"
+            ).fetchall()
+            return [r[0] for r in rows]
+
+        try:
+            async with self._lock:
+                return await self._run(_ns)
+        except Exception:
+            return []
+
+    async def close(self) -> None:
+        if self._conn is not None:
+            self._conn.close()
+            self._conn = None

axor_memory_sqlite-0.1.0.dist-info/METADATA

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: axor-memory-sqlite
+Version: 0.1.0
+Summary: SQLite memory provider for axor-core
+Project-URL: Repository, https://github.com/Bucha11/axor-memory-sqlite
+Project-URL: Bug Tracker, https://github.com/Bucha11/axor-memory-sqlite/issues
+Project-URL: Changelog, https://github.com/Bucha11/axor-memory-sqlite/releases
+License: MIT
+Keywords: agents,axor,memory,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: axor-core>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# axor-memory-sqlite
+
+[![CI](https://github.com/Bucha11/axor-memory-sqlite/actions/workflows/ci.yml/badge.svg)](https://github.com/Bucha11/axor-memory-sqlite/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/axor-memory-sqlite)](https://pypi.org/project/axor-memory-sqlite/)
+[![Python](https://img.shields.io/pypi/pyversions/axor-memory-sqlite)](https://pypi.org/project/axor-memory-sqlite/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**SQLite memory provider for [axor-core](https://github.com/Bucha11/axor-core).**
+
+Persistent cross-session memory for governed agents. Zero extra dependencies — uses Python's built-in `sqlite3`.
+
+---
+
+## Installation
+
+```bash
+pip install axor-memory-sqlite
+```
+
+Requires `axor-core >= 0.1.0`.
+
+---
+
+## Quick Start
+
+```python
+import axor_claude
+from axor_core import AgentDefinition, AgentDomain, FragmentValue, MemoryFragment
+from axor_memory_sqlite import SQLiteMemoryProvider
+
+provider = SQLiteMemoryProvider("~/.axor/memory.db")
+
+session = axor_claude.make_session(
+    api_key="sk-ant-...",
+    agent_def=AgentDefinition(
+        name="my-agent",
+        domain=AgentDomain.CODING,
+        personality="You are an expert Python engineer.",
+        memory_namespaces=("my-agent",),   # loaded at every session start
+    ),
+    memory_provider=provider,
+)
+
+result = await session.run("refactor the auth module")
+
+# save what you want to remember next time
+await provider.save([
+    MemoryFragment(
+        namespace="my-agent",
+        key="auth_module_status",
+        content="Auth module refactored to use JWT. Entry point: auth/jwt.py.",
+        value=FragmentValue.KNOWLEDGE,
+    ),
+])
+```
+
+---
+
+## FragmentValue — what gets remembered how
+
+Every `MemoryFragment` has a `value` that controls how the compressor treats it when it appears in `ContextView`:
+
+| Value | Compressor behavior | Typical use |
+|-------|--------------------|----|
+| `PINNED` | Never touched — survives all turns | User preferences, system rules, agent personality |
+| `KNOWLEDGE` | Dedup + error collapse only — no truncation | Project docs, domain context, API specs |
+| `WORKING` | Normal compression pipeline | Task findings, recent tool results |
+| `EPHEMERAL` | Aggressive compression — evicted first | Debug output, one-turn scratch |
+
+Eviction priority: `EPHEMERAL` → `WORKING` → `KNOWLEDGE` → `PINNED` (never evicted).
+
+---
+
+## API
+
+### `SQLiteMemoryProvider(db_path)`
+
+```python
+from axor_memory_sqlite import SQLiteMemoryProvider
+
+provider = SQLiteMemoryProvider("~/.axor/memory.db")  # persistent
+provider = SQLiteMemoryProvider(":memory:")            # in-memory, tests only
+```
+
+All methods are async. I/O runs in a thread pool — async callers are never blocked.
+
+### `save(fragments)`
+
+Upsert by `(namespace, key)` — existing fragments are overwritten:
+
+```python
+await provider.save([
+    MemoryFragment(
+        namespace="my-agent",
+        key="project_stack",
+        content="FastAPI + async SQLAlchemy + PostgreSQL",
+        value=FragmentValue.PINNED,
+        tags=["stack", "tech"],
+    ),
+])
+```
+
+### `load(query)`
+
+```python
+from axor_core import MemoryQuery, FragmentValue
+
+# load all from namespace, pinned first
+fragments = await provider.load(MemoryQuery(
+    namespaces=("my-agent",),
+    max_results=20,
+))
+
+# filter by value
+pinned = await provider.load(MemoryQuery(
+    namespaces=("my-agent",),
+    values=(FragmentValue.PINNED, FragmentValue.KNOWLEDGE),
+    max_results=10,
+))
+```
+
+Results are ordered by priority (`PINNED` first) then by `accessed_at` descending.
+
+### `delete(namespace, keys)`
+
+```python
+n = await provider.delete("my-agent", ["stale_key_1", "stale_key_2"])
+print(f"deleted {n} fragments")
+```
+
+### `evict(namespace, values, max_age_seconds)`
+
+Remove stale fragments by value and/or age:
+
+```python
+# evict all ephemeral fragments
+await provider.evict("my-agent", values=(FragmentValue.EPHEMERAL,))
+
+# evict working fragments older than 24 hours
+await provider.evict(
+    "my-agent",
+    values=(FragmentValue.WORKING,),
+    max_age_seconds=86400,
+)
+```
+
+### `namespaces()`
+
+```python
+ns = await provider.namespaces()
+# ["my-agent", "shared", "project-x"]
+```
+
+### `close()`
+
+```python
+await provider.close()
+```
+
+Call on shutdown. The provider can be used as an async context manager in tests:
+
+```python
+async with SQLiteMemoryProvider(":memory:") as provider:
+    await provider.save([...])
+```
+
+---
+
+## Namespaces
+
+Namespaces are logical groupings — they do not require explicit creation. A namespace exists as soon as you save a fragment with that name.
+
+Recommended pattern:
+
+| Namespace | Content |
+|-----------|---------|
+| `{agent-name}` | Agent-specific memory — not shared |
+| `shared` | Shared across all agents in a project |
+| `project:{name}` | Project-specific facts |
+| `user:{id}` | Per-user preferences |
+
+```python
+# agent reads from its own namespace + shared
+agent = AgentDefinition(
+    name="billing-agent",
+    memory_namespaces=("billing-agent", "shared"),
+)
+```
+
+---
+
+## Schema
+
+```sql
+CREATE TABLE memory_fragments (
+    namespace    TEXT    NOT NULL,
+    key          TEXT    NOT NULL,
+    content      TEXT    NOT NULL,
+    value        TEXT    NOT NULL DEFAULT 'working',
+    token_count  INTEGER NOT NULL DEFAULT 0,
+    tags         TEXT    NOT NULL DEFAULT '[]',   -- JSON array
+    created_at   TEXT    NOT NULL,
+    accessed_at  TEXT    NOT NULL,
+    metadata     TEXT    NOT NULL DEFAULT '{}',   -- JSON object
+    PRIMARY KEY (namespace, key)
+);
+```
+
+The database file is a standard SQLite file — readable with any SQLite tool.
+
+---
+
+## Testing
+
+Use `:memory:` for tests — no file created, no cleanup needed:
+
+```python
+import pytest
+from axor_memory_sqlite import SQLiteMemoryProvider
+from axor_core import MemoryFragment, FragmentValue, MemoryQuery
+
+@pytest.mark.asyncio
+async def test_memory():
+    p = SQLiteMemoryProvider(":memory:")
+
+    await p.save([
+        MemoryFragment(namespace="test", key="k1",
+                       content="hello", value=FragmentValue.WORKING),
+    ])
+    results = await p.load(MemoryQuery(namespaces=("test",), max_results=5))
+    assert len(results) == 1
+    assert results[0].content == "hello"
+
+    await p.close()
+```
+
+---
+
+## Requirements
+
+- Python 3.11+
+- `axor-core >= 0.1.0`
+- No extra dependencies — uses stdlib `sqlite3` + `asyncio`
+
+---
+
+## License
+
+MIT

axor_memory_sqlite-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+axor_memory_sqlite/__init__.py,sha256=T1yyp1lq90BOHBZ1BZhFgc_wAajvxb94kbOLFa6ZaRM,185
+axor_memory_sqlite/provider.py,sha256=v0RQaVju8RE9_HfhsRl3NEEDIh67ALqTYbQcQypHNmc,9210
+axor_memory_sqlite-0.1.0.dist-info/METADATA,sha256=CuD7yzxPVq_EDba6B-9Tl4dsyXsO0l3PlOTuRbSax04,7317
+axor_memory_sqlite-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+axor_memory_sqlite-0.1.0.dist-info/RECORD,,

axor_memory_sqlite-0.1.0.dist-info/WHEEL

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