ragleap-memory 0.1.0__tar.gz

ragleap_memory-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Environment
+.env
+*.env.local
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+venv/
+.venv/
+
+# Node
+node_modules/
+
+# Docker
+docker-compose.override.yml
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+.env
+
+# Package build artifacts
+dist/
+build/
+
+# RagLeap command
+.ragleap-ollama
+backups/
+
+# Folder grants are the owner's private choices
+grants/*
+!grants/README.txt

ragleap_memory-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to `ragleap-memory` are documented here. Format
+loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.0] - 2026-10-23
+
+First version (design: #900). It replaces an untracked prototype that was never committed, so there are no behaviour changes.
+
+### Added
+
+- `SQLiteStore`: durable memory in one SQLite file with FTS5 keyword search.
+- `add`, `get`, `search`, `supersede`, `forget`, `export`, `erase`, `sweep_expired`, `compact`, `count`, all scoped by a ragleap-security `Scope` inside the SQL.
+- Typed entries (`episode`, `fact`, `summary`) with trust labels (`untrusted` by default), expiry, and links to the entries they were derived from.
+- Optional audit log (ids and counts only, written inside the transaction).
+- `docs/threat-model.md` and `scripts/mutation_check.py` (27 mutations).
+
+### Verified
+
+- 89 tests pass on Python 3.10 (the VPS, SQLite 3.37.2) and on Python 3.12 (the author's sandbox). The CI test job passes on Python 3.10, 3.11 and 3.12 (#922). All 27 mutations are killed on Python 3.10 and 3.12.
+- After `erase()`, a byte-level search of the database file and its journal finds no trace of the deleted text (tested on the two SQLite builds above).
+
+### Not verified
+
+- Windows, network file systems, several processes writing one file, and power-loss durability.
+- Retrieval quality: no benchmark has been run. Multilingual precision is unmeasured (whole-word search is tested for a few scripts).
+- The published wheel had not been installed from PyPI when this was written (the GitHub Release records that check).
+- No independent security review has been done.

ragleap_memory-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: ragleap-memory
+Version: 0.1.0
+Summary: Durable, tenant-scoped long-term memory for LLM applications: typed entries with trust labels, SQLite full-text search, supersession of changed facts, per-scope export and erase, and an optional tamper-evident audit log. Standard library plus ragleap-security. Single-tenant is one fixed scope. Not independently audited.
+Project-URL: Homepage, https://github.com/ragleap/ragleap-core
+Project-URL: Repository, https://github.com/ragleap/ragleap-core
+Project-URL: Issues, https://github.com/ragleap/ragleap-core/issues
+Author: RagLeap
+License-Expression: MIT
+Keywords: byok,fts5,llm,long-term-memory,memory,multi-tenant,self-hosted,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: ragleap-security>=0.1.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# ragleap-memory
+
+Durable, tenant-scoped long-term memory for LLM applications. Alpha. **Not independently audited**: see `docs/threat-model.md` for exactly what is and is not defended. Single-tenant use is simply one fixed `Scope`.
+
+## What is in 0.1.0
+
+- `SQLiteStore`: one SQLite file (or memory), FTS5 keyword search, no server. Needs SQLite built with FTS5; the store refuses to start without it.
+- Every call takes a `Scope` (from ragleap-security) and is filtered by it inside the SQL. A tenant-wide scope sees its whole tenant; a narrower scope sees only its own subject, agent and session.
+- Typed entries (`episode`, `fact`, `summary`) with a trust label (`untrusted`, `model`, `owner`). New entries default to `untrusted`.
+- `supersede` for facts that change (history is kept), `forget`, `export`, `erase` (removes the text from the file), `sweep_expired`, and an optional `AuditLog` that records operations without entry text.
+
+```python
+from ragleap_memory import SQLiteStore
+from ragleap_security import Scope
+
+store = SQLiteStore("memory.db")
+alice = Scope("acme", subject="alice")
+
+old = store.add(alice, "Alice prefers email", trust="owner")
+new = store.supersede(alice, old.id, "Alice prefers phone calls", trust="owner")
+
+for hit in store.search(alice, "how should we contact alice", k=3, min_trust="model"):
+    print(hit.entry.trust, hit.entry.text)
+```
+
+The store labels trust but does not decide what to do with retrieved text. A consumer that puts memory into a prompt must treat anything below `owner` as untrusted input.
+
+## Verifying it yourself
+
+```
+pip install -e ../ragleap-security -e ".[test]"
+pytest
+python scripts/mutation_check.py   # breaks one protection at a time; every mutation must be killed
+```
+
+## Not in 0.1.0
+
+Embeddings and vector search, consolidation and retention policies, importance-based ranking, Postgres, encryption at rest, a review queue and the ragleap-agents adapter are planned (issue #900). Search quality has not been measured on any benchmark.

ragleap_memory-0.1.0/README.md

@@ -0,0 +1,38 @@
+# ragleap-memory
+
+Durable, tenant-scoped long-term memory for LLM applications. Alpha. **Not independently audited**: see `docs/threat-model.md` for exactly what is and is not defended. Single-tenant use is simply one fixed `Scope`.
+
+## What is in 0.1.0
+
+- `SQLiteStore`: one SQLite file (or memory), FTS5 keyword search, no server. Needs SQLite built with FTS5; the store refuses to start without it.
+- Every call takes a `Scope` (from ragleap-security) and is filtered by it inside the SQL. A tenant-wide scope sees its whole tenant; a narrower scope sees only its own subject, agent and session.
+- Typed entries (`episode`, `fact`, `summary`) with a trust label (`untrusted`, `model`, `owner`). New entries default to `untrusted`.
+- `supersede` for facts that change (history is kept), `forget`, `export`, `erase` (removes the text from the file), `sweep_expired`, and an optional `AuditLog` that records operations without entry text.
+
+```python
+from ragleap_memory import SQLiteStore
+from ragleap_security import Scope
+
+store = SQLiteStore("memory.db")
+alice = Scope("acme", subject="alice")
+
+old = store.add(alice, "Alice prefers email", trust="owner")
+new = store.supersede(alice, old.id, "Alice prefers phone calls", trust="owner")
+
+for hit in store.search(alice, "how should we contact alice", k=3, min_trust="model"):
+    print(hit.entry.trust, hit.entry.text)
+```
+
+The store labels trust but does not decide what to do with retrieved text. A consumer that puts memory into a prompt must treat anything below `owner` as untrusted input.
+
+## Verifying it yourself
+
+```
+pip install -e ../ragleap-security -e ".[test]"
+pytest
+python scripts/mutation_check.py   # breaks one protection at a time; every mutation must be killed
+```
+
+## Not in 0.1.0
+
+Embeddings and vector search, consolidation and retention policies, importance-based ranking, Postgres, encryption at rest, a review queue and the ragleap-agents adapter are planned (issue #900). Search quality has not been measured on any benchmark.

ragleap_memory-0.1.0/docs/threat-model.md

@@ -0,0 +1,31 @@
+# ragleap-memory 0.1.0: threat model
+
+Status: first version. It covers only what 0.1.0 contains. Anything not listed as defended is not defended. This library has had no independent security review.
+
+## Scope of 0.1.0
+
+`SQLiteStore`: durable memory in one SQLite file (or in memory) with FTS5 keyword search, typed entries with trust labels, supersession, per-scope export and erase, and an optional audit log. It uses `Scope`, `AuditLog` and the limits from ragleap-security 0.1.0. Nothing in `core/` or ragleap-rag uses it yet.
+
+## Threats
+
+| # | Threat | What 0.1.0 does | Backed by | Not defended |
+|---|--------|-----------------|-----------|--------------|
+| 1 | One tenant reads, changes or deletes another tenant's entries | Every operation requires an exact `Scope`. The scope is applied inside the SQL (tenant plus any narrower subject, agent and session). `derived_from` ids must be visible to the writer's scope. A missing entry and an invisible entry give the same error. | `tests/test_isolation.py`, `tests/test_add_validation.py`, `tests/test_lifecycle.py`; 11 mutations in `scripts/mutation_check.py` | The caller chooses the scope. The store cannot know whether a caller is entitled to it: authentication and mapping users to scopes belong to the application. Anyone who can read the database file or hold the store object bypasses it. A tenant-wide scope sees everything in its tenant by design. |
+| 2 | Untrusted or poisoned text is later treated as trustworthy | Every entry carries a trust label (`untrusted`, `model`, `owner`); the default is the lowest; `min_trust` filters searches; derived entries record their sources. | `tests/test_search.py`, `tests/test_add_validation.py`; 2 mutations | Labels are only as honest as whoever writes them: a writer can claim `owner`. The store does not stop a consumer from putting retrieved text into a prompt as instructions. Defending against prompt injection through retrieved memory is the consumer's job (the ragleap-agents integration is planned). No content scanning. |
+| 3 | A search query changes the query, or is used to exhaust resources | Queries are reduced to quoted words joined with OR, so operators are plain words; at most 32 words and 1,000 bytes; results are capped (default 50). | `tests/test_search.py`, `tests/test_isolation.py`; 3 mutations | A slow query inside these limits on a very large store. No timing has been measured. |
+| 4 | Deleted text stays in the database file | `erase()` deletes, rewrites the full-text index, and checkpoints the journal; `secure_delete` is turned on explicitly. A byte-level test checks the text is gone from the file. | `tests/test_lifecycle.py`; 2 mutations | `forget()` leaves traces in the search index until `compact()` or `erase()` runs (a test pins this). Other SQLite builds, other operating systems, file system journals, SSD wear levelling, backups, snapshots and copies of the file are **not verified**. |
+| 5 | A change happens without a record, or half-happens | The optional `AuditLog` is written inside the transaction, so a failing audit write rolls the change back; the log holds ids and counts, never entry text; any error rolls the whole write back. | `tests/test_durability.py`; 2 mutations | The audit log is optional and off by default. Reads (`get`, `search`, `count`) are not audited, only `export`. The log is tamper-evident, not tamper-proof (see the ragleap-security threat model). |
+| 6 | Oversized input exhausts memory or disk | Text is capped at 8,192 bytes; metadata at 4,096 bytes, depth 8 and 1,000 values; `derived_from` at 100 ids; `forget` at 1,000 ids. | `tests/test_add_validation.py`; 2 mutations | No cap on the number of entries per tenant or on the file size: a tenant can fill the disk. No rate limiting. |
+| 7 | The database file is readable by other local users | The file is created with mode 0600. Checked by hand on Linux, SQLite's `-wal` and `-shm` files were 0600 too; the test checks only the main file. | `tests/test_durability.py`; 1 mutation | A file that already exists keeps its permissions. No encryption at rest (planned with ragleap-security `crypto`, not in 0.1.0). Backups. |
+| 8 | A newer schema is opened by older code, or writers collide | A database with a newer schema version is refused; writes run in `BEGIN IMMEDIATE` transactions with WAL; threads share one locked connection. | `tests/test_durability.py` (8 threads, 200 writes); 1 mutation | Several processes writing the same file, network file systems and power-loss durability beyond SQLite's defaults are **not verified**. |
+| 9 | An outdated or expired fact is used as if current | Expired and superseded entries are hidden from search unless asked; `supersede` links the new entry to the old one and refuses a second supersession. | `tests/test_search.py`, `tests/test_lifecycle.py`; 3 mutations | The store cannot know a fact is wrong. Two contradicting entries added with `add()` both stay current. |
+
+## Not covered in 0.1.0
+
+Encryption at rest, embeddings and vector search, consolidation, retention and decay beyond expiry, importance-based ranking (importance is stored but does not affect ranking yet), Postgres, a review queue, and the ragleap-agents adapter. Retrieval quality has not been measured on any benchmark.
+
+Languages: search uses SQLite's `unicode61` tokenizer. Whole-word search is tested for Hindi, Tamil, Arabic and Chinese written with spaces. Chinese or Japanese text without spaces is not split into words. Words in Indic scripts are split at combining marks, so partial matches can be loose; precision has not been measured.
+
+## How this document is checked
+
+`python scripts/mutation_check.py` breaks one protection at a time in a temporary copy and requires a test to fail. All 27 listed mutations were killed when this version was written. A killed mutation shows a protection is exercised by a test; it does not show the protection is sufficient.

ragleap_memory-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ragleap-memory"
+version = "0.1.0"
+description = "Durable, tenant-scoped long-term memory for LLM applications: typed entries with trust labels, SQLite full-text search, supersession of changed facts, per-scope export and erase, and an optional tamper-evident audit log. Standard library plus ragleap-security. Single-tenant is one fixed scope. Not independently audited."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "RagLeap" }
+]
+keywords = ["memory", "llm", "long-term-memory", "multi-tenant", "sqlite", "fts5", "self-hosted", "byok"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "ragleap-security>=0.1.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8.0.0"]
+
+[project.urls]
+Homepage = "https://github.com/ragleap/ragleap-core"
+Repository = "https://github.com/ragleap/ragleap-core"
+Issues = "https://github.com/ragleap/ragleap-core/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ragleap_memory"]

ragleap_memory-0.1.0/scripts/mutation_check.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Mutation check for ragleap-memory (repository only, not part of the installed package).
+
+For each mutation below it copies the package to a temp directory, breaks one protection in the
+copy, and runs the test suite. A mutation is KILLED if a test fails, SURVIVED if every test still
+passes (meaning that protection is not really tested). The real source is never modified.
+
+  python scripts/mutation_check.py
+
+Needs ragleap-security importable (installed, or on PYTHONPATH). Exit code 0 only if the unmodified
+suite passes and every mutation is killed. Run from the package directory. A killed mutation shows a
+protection is exercised by a test; it does not show the protection is sufficient."""
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+PKG = Path(__file__).resolve().parent.parent
+S = "src/ragleap_memory/sqlite_store.py"
+
+# (name, [(file, old, new), ...]) ; each old string must occur exactly once in its file
+MUTATIONS = [
+    ("scope clause ignores the tenant", [(S, 'parts, params = [f"{p}tenant = ?"], [scope.tenant]', 'parts, params = ["1 = 1"], []')]),
+    ("scope clause ignores narrower parts", [(S, "        if v is not None:\n            parts.append(", "        if False:\n            parts.append(")]),
+    ("get checks ids but not the scope", [(S, 'row = db.execute(f"SELECT * FROM memories WHERE id = ? AND {clause}", [entry_id, *params]).fetchone()', 'row = db.execute("SELECT * FROM memories WHERE id = ?", [entry_id]).fetchone()')]),
+    ("search drops the scope condition", [(S, 'f" WHERE memories_fts MATCH ? AND {clause}"', 'f" WHERE memories_fts MATCH ? AND 1 = 1"'), (S, "args: list = [match, *params, *kinds, *trusts]", "args: list = [match, *kinds, *trusts]")]),
+    ("forget deletes by id only", [(S, 'n = db.execute(f"DELETE FROM memories WHERE id IN ({\',\'.join(\'?\' * len(ids))}) AND {clause}",\n                           [*ids, *params]).rowcount', 'n = db.execute(f"DELETE FROM memories WHERE id IN ({\',\'.join(\'?\' * len(ids))})",\n                           [*ids]).rowcount')]),
+    ("erase deletes everything", [(S, 'n = db.execute(f"DELETE FROM memories WHERE {clause}", params).rowcount\n            self._log("memory.erase"', 'n = db.execute("DELETE FROM memories").rowcount\n            self._log("memory.erase"')]),
+    ("sweep ignores the scope", [(S, 'n = db.execute(f"DELETE FROM memories WHERE {clause} AND expires_at IS NOT NULL AND expires_at <= ?",\n                           [*params, _iso(self._clock())]).rowcount', 'n = db.execute("DELETE FROM memories WHERE expires_at IS NOT NULL AND expires_at <= ?",\n                           [_iso(self._clock())]).rowcount')]),
+    ("export ignores the scope", [(S, 'rows = db.execute(f"SELECT * FROM memories WHERE {clause} ORDER BY created_at, id", params).fetchall()', 'rows = db.execute("SELECT * FROM memories ORDER BY created_at, id").fetchall()')]),
+    ("count ignores the scope", [(S, 'return self._db.execute(f"SELECT COUNT(*) FROM memories WHERE {clause}", params).fetchone()[0]', 'return self._db.execute("SELECT COUNT(*) FROM memories").fetchone()[0]')]),
+    ("derived_from not checked against the scope", [(S, "            for d in derived:\n                self._visible(db, scope, d)\n", "            for d in derived:\n                pass\n")]),
+    ("supersede does not check the scope", [(S, "            old = self._visible(db, scope, old_id)\n", '            old = db.execute("SELECT * FROM memories WHERE id = ?", [old_id]).fetchone()\n            if old is None:\n                raise NotFoundError("no such entry")\n')]),
+    ("double supersede allowed", [(S, 'if old["superseded_by"] is not None:', "if False:")]),
+    ("default trust raised to owner", [(S, 'source: str = "api", trust: str = "untrusted",\n            importance: float = 0.5', 'source: str = "api", trust: str = "owner",\n            importance: float = 0.5')]),
+    ("min_trust ignored", [(S, "trusts = [t for t in TRUSTS if trust_rank(t) >= trust_rank(min_trust)]", "trusts = list(TRUSTS)")]),
+    ("expired entries not hidden", [(S, "        if not include_expired:\n            sql +=", "        if False:\n            sql +=")]),
+    ("superseded entries not hidden", [(S, "        if not include_superseded:\n            sql +=", "        if False:\n            sql +=")]),
+    ("query words not quoted", [(S, """match = " OR ".join('"%s"' % t for t in tokens)""", """match = " OR ".join(tokens)""")]),
+    ("query size not limited", [(S, 'check_size(query, 1000, "query")', "pass")]),
+    ("result cap removed", [(S, "k = min(k, self.max_results)", "pass")]),
+    ("text size not limited", [(S, "check_size(text, self.max_text_bytes, \"text\")", "pass")]),
+    ("metadata shape not limited", [(S, "check_json_shape(metadata, max_depth=8, max_nodes=1000)", "pass")]),
+    ("audit written after the transaction (not rolled back)", [(S, "        if self._audit is not None:  # inside the transaction: if the audit write fails, the change is rolled back\n            self._audit.append(event, data, scope)", "        pass")]),
+    ("secure_delete explicitly off", [(S, 'self._db.execute("PRAGMA secure_delete = ON")', 'self._db.execute("PRAGMA secure_delete = OFF")')]),
+    ("erase does not compact", [(S, "            self._log(\"memory.erase\", scope, {\"count\": n})\n        self.compact()", "            self._log(\"memory.erase\", scope, {\"count\": n})")]),
+    ("database file not private", [(S, "os.O_WRONLY | os.O_CREAT, 0o600", "os.O_WRONLY | os.O_CREAT, 0o644")]),
+    ("newer schema accepted", [(S, "if version > SCHEMA_VERSION:", "if False:")]),
+    ("failed write not rolled back", [(S, '                self._db.execute("ROLLBACK")\n                raise', "                raise")]),
+]
+
+
+def run_tests(root: Path) -> bool:
+    env = dict(os.environ, PYTHONDONTWRITEBYTECODE="1",
+               PYTHONPATH=os.pathsep.join(p for p in (str(root / "src"), os.environ.get("PYTHONPATH", "")) if p))
+    r = subprocess.run([sys.executable, "-m", "pytest", "-q", "-x", "-p", "no:cacheprovider", str(root / "tests")],
+                       cwd=root, env=env, capture_output=True, text=True)
+    return r.returncode == 0
+
+
+def main() -> int:
+    survivors = []
+    with tempfile.TemporaryDirectory() as tmp:
+        base = Path(tmp) / "base"
+        shutil.copytree(PKG, base, ignore=shutil.ignore_patterns("__pycache__", ".pytest_cache", "scripts"))
+        if not run_tests(base):
+            print("The unmodified test suite fails; fix that first.")
+            return 2
+        print("baseline: tests pass")
+        for i, (name, edits) in enumerate(MUTATIONS):
+            work = Path(tmp) / f"m{i}"
+            shutil.copytree(base, work)
+            for rel, old, new in edits:
+                p = work / rel
+                text = p.read_text()
+                if text.count(old) != 1:
+                    print(f"ERROR  {name}: anchor not found exactly once in {rel}")
+                    return 2
+                p.write_text(text.replace(old, new))
+            killed = not run_tests(work)
+            print(("KILLED   " if killed else "SURVIVED ") + name)
+            if not killed:
+                survivors.append(name)
+            shutil.rmtree(work)
+    print(f"\n{len(MUTATIONS) - len(survivors)} of {len(MUTATIONS)} mutations killed")
+    return 1 if survivors else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ragleap_memory-0.1.0/src/ragleap_memory/__init__.py

@@ -0,0 +1,13 @@
+"""ragleap-memory: durable, tenant-scoped long-term memory for LLM applications.
+
+Needs SQLite with FTS5. Not independently audited. See docs/threat-model.md."""
+from ragleap_memory.model import (KINDS, TRUSTS, InvalidEntryError, MemoryEntry, MemoryStoreError, NotFoundError,
+                                  SearchHit)
+from ragleap_memory.sqlite_store import SCHEMA_VERSION, SQLiteStore
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "InvalidEntryError", "KINDS", "MemoryEntry", "MemoryStoreError", "NotFoundError", "SCHEMA_VERSION",
+    "SQLiteStore", "SearchHit", "TRUSTS", "__version__",
+]

ragleap_memory-0.1.0/src/ragleap_memory/model.py

@@ -0,0 +1,63 @@
+"""Data model for ragleap-memory: entries, search hits, trust labels and errors."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, Tuple
+
+from ragleap_security import Scope
+
+KINDS = ("episode", "fact", "summary")
+# Lowest to highest. "owner": written by the owner. "model": written by a model. "untrusted": derived
+# from content nobody vouched for. The default for new entries is the lowest.
+TRUSTS = ("untrusted", "model", "owner")
+
+ID_RE = re.compile(r"[0-9a-f]{32}\Z")
+SOURCE_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,127}\Z")
+
+
+class MemoryStoreError(Exception):
+    """Base class for memory store errors. Messages never contain entry text."""
+
+
+class InvalidEntryError(MemoryStoreError, ValueError):
+    """An entry or argument is invalid."""
+
+
+class NotFoundError(MemoryStoreError):
+    """No such entry, or it is not visible to the scope that asked. The two cases look the same."""
+
+
+def trust_rank(trust: str) -> int:
+    return TRUSTS.index(trust)
+
+
+@dataclass(frozen=True)
+class MemoryEntry:
+    id: str
+    scope: Scope
+    kind: str
+    text: str
+    source: str
+    trust: str
+    importance: float
+    created_at: str
+    expires_at: "str | None" = None
+    superseded_by: "str | None" = None
+    derived_from: Tuple[str, ...] = ()
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id, "scope": self.scope.key, "kind": self.kind, "text": self.text,
+            "source": self.source, "trust": self.trust, "importance": self.importance,
+            "created_at": self.created_at, "expires_at": self.expires_at,
+            "superseded_by": self.superseded_by, "derived_from": list(self.derived_from),
+            "metadata": self.metadata,
+        }
+
+
+@dataclass(frozen=True)
+class SearchHit:
+    entry: MemoryEntry
+    score: float  # higher is more relevant (negated SQLite bm25)

ragleap_memory-0.1.0/src/ragleap_memory/sqlite_store.py

@@ -0,0 +1,322 @@
+"""SQLiteStore: durable memory in one SQLite file (or in memory), with FTS5 keyword search.
+
+Every operation takes a Scope and is filtered by it inside the SQL, not by the caller. A scope sees
+the entries whose scope it covers: a tenant-wide scope sees everything in the tenant, a narrower scope
+sees only its own subject/agent/session, and an entry without a subject is not visible to a scope that
+names one."""
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import re
+import sqlite3
+import threading
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Iterable, Iterator, List, Optional, Sequence
+
+from ragleap_security import (AuditLog, Scope, check_json_shape, check_size, require_scope)
+
+from .model import (ID_RE, KINDS, SOURCE_RE, TRUSTS, InvalidEntryError, MemoryEntry, MemoryStoreError,
+                    NotFoundError, SearchHit, trust_rank)
+
+SCHEMA_VERSION = 1
+_SCOPE_FIELDS = ("tenant", "subject", "agent", "session")
+_TOKEN = re.compile(r"\w+")
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS memories(
+    rowid INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL UNIQUE,
+    tenant TEXT NOT NULL, subject TEXT, agent TEXT, session TEXT,
+    kind TEXT NOT NULL CHECK(kind IN ('episode','fact','summary')),
+    text TEXT NOT NULL,
+    source TEXT NOT NULL,
+    trust TEXT NOT NULL CHECK(trust IN ('untrusted','model','owner')),
+    importance REAL NOT NULL CHECK(importance >= 0 AND importance <= 1),
+    created_at TEXT NOT NULL,
+    expires_at TEXT,
+    superseded_by TEXT,
+    derived_from TEXT NOT NULL,
+    metadata TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS memories_scope ON memories(tenant, subject, agent, session);
+CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+    text, content='memories', content_rowid='rowid', tokenize='unicode61 remove_diacritics 2');
+CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+    INSERT INTO memories_fts(rowid, text) VALUES (new.rowid, new.text);
+END;
+CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+    INSERT INTO memories_fts(memories_fts, rowid, text) VALUES ('delete', old.rowid, old.text);
+END;
+"""
+
+
+def _iso(dt: datetime) -> str:
+    return dt.astimezone(timezone.utc).isoformat(timespec="microseconds")
+
+
+def _scope_clause(scope: Scope, alias: str = "") -> "tuple[str, list]":
+    """SQL condition that matches exactly the entries `scope` covers."""
+    p = f"{alias}." if alias else ""
+    parts, params = [f"{p}tenant = ?"], [scope.tenant]
+    for f in _SCOPE_FIELDS[1:]:
+        v = getattr(scope, f)
+        if v is not None:
+            parts.append(f"{p}{f} = ?")
+            params.append(v)
+    return " AND ".join(parts), params
+
+
+def _row_to_entry(row: sqlite3.Row) -> MemoryEntry:
+    return MemoryEntry(
+        id=row["id"],
+        scope=Scope(row["tenant"], row["subject"], row["agent"], row["session"]),
+        kind=row["kind"], text=row["text"], source=row["source"], trust=row["trust"],
+        importance=row["importance"], created_at=row["created_at"], expires_at=row["expires_at"],
+        superseded_by=row["superseded_by"], derived_from=tuple(json.loads(row["derived_from"])),
+        metadata=json.loads(row["metadata"]),
+    )
+
+
+class SQLiteStore:
+    def __init__(self, path: str = ":memory:", *, audit: Optional[AuditLog] = None,
+                 clock: Optional[Callable[[], datetime]] = None, max_text_bytes: int = 8192,
+                 max_results: int = 50):
+        self.path = os.fspath(path)
+        self._audit = audit
+        self._clock = clock or (lambda: datetime.now(timezone.utc))
+        self.max_text_bytes = max_text_bytes
+        self.max_results = max_results
+        self._lock = threading.RLock()
+        if self.path != ":memory:" and not os.path.exists(self.path):
+            os.close(os.open(self.path, os.O_WRONLY | os.O_CREAT, 0o600))
+        self._db = sqlite3.connect(self.path, check_same_thread=False, isolation_level=None)
+        self._db.row_factory = sqlite3.Row
+        self._db.execute("PRAGMA busy_timeout = 5000")
+        self._db.execute("PRAGMA secure_delete = ON")
+        if self.path != ":memory:":
+            self._db.execute("PRAGMA journal_mode = WAL")
+        version = self._db.execute("PRAGMA user_version").fetchone()[0]
+        if version > SCHEMA_VERSION:
+            self._db.close()
+            raise MemoryStoreError(f"database schema version {version} is newer than this library supports")
+        try:
+            self._db.executescript(_SCHEMA)
+        except sqlite3.OperationalError as e:
+            self._db.close()
+            raise MemoryStoreError("SQLite with FTS5 is required: %s" % e) from None
+        self._db.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")
+
+    # -- helpers -----------------------------------------------------------------------------------
+
+    @contextlib.contextmanager
+    def _tx(self) -> Iterator[sqlite3.Connection]:
+        with self._lock:
+            self._db.execute("BEGIN IMMEDIATE")
+            try:
+                yield self._db
+            except BaseException:
+                self._db.execute("ROLLBACK")
+                raise
+            else:
+                self._db.execute("COMMIT")
+
+    def _log(self, event: str, scope: Scope, data: Dict[str, Any]) -> None:
+        if self._audit is not None:  # inside the transaction: if the audit write fails, the change is rolled back
+            self._audit.append(event, data, scope)
+
+    def _visible(self, db: sqlite3.Connection, scope: Scope, entry_id: str) -> sqlite3.Row:
+        clause, params = _scope_clause(scope)
+        row = db.execute(f"SELECT * FROM memories WHERE id = ? AND {clause}", [entry_id, *params]).fetchone()
+        if row is None:
+            raise NotFoundError("no such entry")
+        return row
+
+    def _validate_new(self, scope: Any, text: Any, kind: str, source: str, trust: str, importance: Any,
+                      expires_at: Any, metadata: Any) -> "tuple[Scope, str | None, str]":
+        scope = require_scope(scope)
+        if kind not in KINDS:
+            raise InvalidEntryError("invalid kind")
+        if trust not in TRUSTS:
+            raise InvalidEntryError("invalid trust")
+        if not isinstance(source, str) or not SOURCE_RE.match(source):
+            raise InvalidEntryError("invalid source")
+        if isinstance(importance, bool) or not isinstance(importance, (int, float)) or not 0 <= importance <= 1:
+            raise InvalidEntryError("importance must be a number from 0 to 1")
+        if not isinstance(text, str) or not text.strip():
+            raise InvalidEntryError("text must be a non-empty string")
+        check_size(text, self.max_text_bytes, "text")
+        exp = None
+        if expires_at is not None:
+            if not isinstance(expires_at, datetime) or expires_at.tzinfo is None:
+                raise InvalidEntryError("expires_at must be a timezone-aware datetime")
+            exp = _iso(expires_at)
+        if metadata is None:
+            metadata = {}
+        if not isinstance(metadata, dict):
+            raise InvalidEntryError("metadata must be a dict")
+        check_json_shape(metadata, max_depth=8, max_nodes=1000)
+        try:
+            meta_json = json.dumps(metadata, sort_keys=True)
+        except (TypeError, ValueError):
+            raise InvalidEntryError("metadata must be JSON serializable") from None
+        check_size(meta_json, 4096, "metadata")
+        return scope, exp, meta_json
+
+    def _insert(self, db: sqlite3.Connection, scope: Scope, text: str, kind: str, source: str, trust: str,
+                importance: float, exp: Optional[str], derived: Sequence[str], meta_json: str) -> MemoryEntry:
+        entry_id = uuid.uuid4().hex
+        created = _iso(self._clock())
+        db.execute(
+            "INSERT INTO memories(id, tenant, subject, agent, session, kind, text, source, trust, importance,"
+            " created_at, expires_at, superseded_by, derived_from, metadata) VALUES (?,?,?,?,?,?,?,?,?,?,?,?,NULL,?,?)",
+            [entry_id, scope.tenant, scope.subject, scope.agent, scope.session, kind, text, source, trust,
+             float(importance), created, exp, json.dumps(list(derived)), meta_json])
+        return _row_to_entry(db.execute("SELECT * FROM memories WHERE id = ?", [entry_id]).fetchone())
+
+    # -- public API --------------------------------------------------------------------------------
+
+    def add(self, scope: Scope, text: str, *, kind: str = "fact", source: str = "api", trust: str = "untrusted",
+            importance: float = 0.5, expires_at: Optional[datetime] = None, derived_from: Iterable[str] = (),
+            metadata: Optional[Dict[str, Any]] = None) -> MemoryEntry:
+        """Store an entry in exactly `scope`. trust defaults to the lowest level ("untrusted"): say
+        "model" or "owner" explicitly. Every id in derived_from must be visible to `scope`."""
+        scope, exp, meta_json = self._validate_new(scope, text, kind, source, trust, importance, expires_at, metadata)
+        derived = list(derived_from)
+        if len(derived) > 100 or len(set(derived)) != len(derived) or not all(isinstance(d, str) and ID_RE.match(d) for d in derived):
+            raise InvalidEntryError("derived_from must be up to 100 distinct entry ids")
+        with self._tx() as db:
+            for d in derived:
+                self._visible(db, scope, d)
+            entry = self._insert(db, scope, text, kind, source, trust, importance, exp, derived, meta_json)
+            self._log("memory.add", scope, {"id": entry.id, "kind": kind, "trust": trust})
+        return entry
+
+    def get(self, scope: Scope, entry_id: str) -> MemoryEntry:
+        scope = require_scope(scope)
+        with self._lock:
+            return _row_to_entry(self._visible(self._db, scope, entry_id))
+
+    def count(self, scope: Scope) -> int:
+        scope = require_scope(scope)
+        clause, params = _scope_clause(scope)
+        with self._lock:
+            return self._db.execute(f"SELECT COUNT(*) FROM memories WHERE {clause}", params).fetchone()[0]
+
+    def search(self, scope: Scope, query: str, *, k: int = 5, kinds: Optional[Sequence[str]] = None,
+               min_trust: str = "untrusted", include_superseded: bool = False,
+               include_expired: bool = False) -> List[SearchHit]:
+        """Keyword search (FTS5, bm25) over the entries `scope` can see. The query is split into
+        words; any word may match. Operators in the query are treated as plain words."""
+        scope = require_scope(scope)
+        if not isinstance(query, str):
+            raise InvalidEntryError("query must be a string")
+        check_size(query, 1000, "query")
+        if isinstance(k, bool) or not isinstance(k, int) or k < 1:
+            raise InvalidEntryError("k must be a positive int")
+        k = min(k, self.max_results)
+        if min_trust not in TRUSTS:
+            raise InvalidEntryError("invalid min_trust")
+        kinds = tuple(kinds) if kinds is not None else KINDS
+        if not kinds or any(x not in KINDS for x in kinds):
+            raise InvalidEntryError("invalid kinds")
+        tokens = _TOKEN.findall(query)[:32]
+        if not tokens:
+            return []
+        match = " OR ".join('"%s"' % t for t in tokens)
+        clause, params = _scope_clause(scope, "m")
+        trusts = [t for t in TRUSTS if trust_rank(t) >= trust_rank(min_trust)]
+        sql = (f"SELECT m.*, bm25(memories_fts) AS score FROM memories_fts JOIN memories m ON m.rowid = memories_fts.rowid"
+               f" WHERE memories_fts MATCH ? AND {clause}"
+               f" AND m.kind IN ({','.join('?' * len(kinds))}) AND m.trust IN ({','.join('?' * len(trusts))})")
+        args: list = [match, *params, *kinds, *trusts]
+        if not include_superseded:
+            sql += " AND m.superseded_by IS NULL"
+        if not include_expired:
+            sql += " AND (m.expires_at IS NULL OR m.expires_at > ?)"
+            args.append(_iso(self._clock()))
+        sql += " ORDER BY score, m.created_at DESC LIMIT ?"
+        args.append(k)
+        with self._lock:
+            rows = self._db.execute(sql, args).fetchall()
+        return [SearchHit(_row_to_entry(r), -float(r["score"])) for r in rows]
+
+    def supersede(self, scope: Scope, old_id: str, text: str, *, kind: Optional[str] = None, source: str = "api",
+                  trust: str = "untrusted", importance: Optional[float] = None,
+                  expires_at: Optional[datetime] = None, metadata: Optional[Dict[str, Any]] = None) -> MemoryEntry:
+        """Replace an entry whose content changed. The new entry gets the old entry's exact scope; the
+        old one stays in the store (see export, include_superseded) and points at its replacement."""
+        scope = require_scope(scope)
+        with self._tx() as db:
+            old = self._visible(db, scope, old_id)
+            if old["superseded_by"] is not None:
+                raise InvalidEntryError("entry is already superseded")
+            old_scope = Scope(old["tenant"], old["subject"], old["agent"], old["session"])
+            kind = kind or old["kind"]
+            importance = old["importance"] if importance is None else importance
+            _, exp, meta_json = self._validate_new(old_scope, text, kind, source, trust, importance, expires_at, metadata)
+            new = self._insert(db, old_scope, text, kind, source, trust, importance, exp, [old_id], meta_json)
+            db.execute("UPDATE memories SET superseded_by = ? WHERE id = ?", [new.id, old_id])
+            self._log("memory.supersede", scope, {"old": old_id, "new": new.id})
+        return new
+
+    def forget(self, scope: Scope, ids: Iterable[str]) -> int:
+        """Delete the listed entries that `scope` can see; returns how many were deleted. They stop
+        appearing in searches at once, but traces can stay in the database file until compact()
+        or erase() runs."""
+        scope = require_scope(scope)
+        ids = list(ids)
+        if len(ids) > 1000 or not all(isinstance(i, str) and ID_RE.match(i) for i in ids):
+            raise InvalidEntryError("ids must be up to 1000 entry ids")
+        if not ids:
+            return 0
+        clause, params = _scope_clause(scope)
+        with self._tx() as db:
+            n = db.execute(f"DELETE FROM memories WHERE id IN ({','.join('?' * len(ids))}) AND {clause}",
+                           [*ids, *params]).rowcount
+            self._log("memory.forget", scope, {"count": n})
+        return n
+
+    def export(self, scope: Scope) -> List[Dict[str, Any]]:
+        """Every entry `scope` can see (superseded and expired ones too) as plain dicts."""
+        scope = require_scope(scope)
+        clause, params = _scope_clause(scope)
+        with self._tx() as db:
+            rows = db.execute(f"SELECT * FROM memories WHERE {clause} ORDER BY created_at, id", params).fetchall()
+            self._log("memory.export", scope, {"count": len(rows)})
+        return [_row_to_entry(r).to_dict() for r in rows]
+
+    def erase(self, scope: Scope) -> int:
+        """Delete everything `scope` can see, then rewrite the search index and checkpoint the
+        journal so the deleted text is no longer in the database file. Returns the number deleted."""
+        scope = require_scope(scope)
+        clause, params = _scope_clause(scope)
+        with self._tx() as db:
+            n = db.execute(f"DELETE FROM memories WHERE {clause}", params).rowcount
+            self._log("memory.erase", scope, {"count": n})
+        self.compact()
+        return n
+
+    def sweep_expired(self, scope: Scope) -> int:
+        """Delete expired entries inside `scope`; returns how many."""
+        scope = require_scope(scope)
+        clause, params = _scope_clause(scope)
+        with self._tx() as db:
+            n = db.execute(f"DELETE FROM memories WHERE {clause} AND expires_at IS NOT NULL AND expires_at <= ?",
+                           [*params, _iso(self._clock())]).rowcount
+            self._log("memory.sweep", scope, {"count": n})
+        return n
+
+    def compact(self) -> None:
+        """Rewrite the full-text index and checkpoint the journal. Needed to remove deleted text from
+        the file; erase() calls it. Can take a while on a large store."""
+        with self._lock:
+            self._db.execute("INSERT INTO memories_fts(memories_fts) VALUES ('optimize')")
+            if self.path != ":memory:":
+                self._db.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+
+    def close(self) -> None:
+        with self._lock:
+            self._db.close()

ragleap_memory-0.1.0/tests/conftest.py

@@ -0,0 +1,10 @@
+import pytest
+
+from ragleap_memory import SQLiteStore
+
+
+@pytest.fixture
+def store():
+    s = SQLiteStore()
+    yield s
+    s.close()

ragleap_memory-0.1.0/tests/test_add_validation.py

@@ -0,0 +1,96 @@
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+from ragleap_memory import InvalidEntryError, NotFoundError
+from ragleap_security import LimitError, Scope, SecretStr
+
+A = Scope("acme")
+
+
+def test_add_returns_entry_with_safe_defaults(store):
+    e = store.add(A, "hello world")
+    assert e.scope == A and e.kind == "fact" and e.trust == "untrusted" and e.importance == 0.5
+    assert len(e.id) == 32 and e.superseded_by is None and e.derived_from == () and e.metadata == {}
+    assert store.get(A, e.id) == e
+
+
+def test_explicit_trust_kind_source_importance_metadata(store):
+    e = store.add(A, "x y", kind="summary", source="agent:planner", trust="owner", importance=1, metadata={"k": [1, 2]})
+    assert (e.kind, e.source, e.trust, e.importance, e.metadata) == ("summary", "agent:planner", "owner", 1, {"k": [1, 2]})
+
+
+@pytest.mark.parametrize("bad", ["", "   ", None, 5, b"bytes"])
+def test_bad_text_refused(store, bad):
+    with pytest.raises(InvalidEntryError):
+        store.add(A, bad)
+
+
+def test_text_size_limit_counts_bytes_and_boundary(store):
+    store.add(A, "a" * 8192)  # positive control: exactly at the limit
+    with pytest.raises(LimitError):
+        store.add(A, "a" * 8193)
+    with pytest.raises(LimitError):
+        store.add(A, "é" * 4097)  # 8194 bytes
+
+
+@pytest.mark.parametrize("field,value", [("kind", "note"), ("trust", "admin"), ("source", ""), ("source", "a b"),
+                                         ("source", "-x"), ("importance", -0.1), ("importance", 1.1),
+                                         ("importance", True), ("importance", "high"), ("importance", None)])
+def test_bad_fields_refused(store, field, value):
+    with pytest.raises(InvalidEntryError):
+        store.add(A, "text", **{field: value})
+
+
+@pytest.mark.parametrize("scope", ["tenant=acme", None, {"tenant": "acme"}, 5])
+def test_scope_must_be_a_scope(store, scope):
+    with pytest.raises(Exception) as e:
+        store.add(scope, "text")
+    assert type(e.value).__name__ == "ScopeError"
+    assert store.count(A) == 0
+
+
+def test_metadata_rules(store):
+    for bad in ([1], "x", 5):
+        with pytest.raises(InvalidEntryError):
+            store.add(A, "t", metadata=bad)
+    with pytest.raises(InvalidEntryError):
+        store.add(A, "t", metadata={"k": SecretStr("abcdefgh")})  # not JSON serializable
+    with pytest.raises(InvalidEntryError):
+        store.add(A, "t", metadata={"k": object()})
+    with pytest.raises(LimitError):
+        store.add(A, "t", metadata={"k": "x" * 5000})
+    deep = cur = {}
+    for _ in range(20):
+        cur["n"] = {}
+        cur = cur["n"]
+    with pytest.raises(LimitError):
+        store.add(A, "t", metadata=deep)
+    store.add(A, "t", metadata={"k": "x" * 4000})  # positive control under the size limit
+
+
+def test_expires_at_must_be_aware(store):
+    with pytest.raises(InvalidEntryError):
+        store.add(A, "t", expires_at=datetime.now())
+    with pytest.raises(InvalidEntryError):
+        store.add(A, "t", expires_at="2030-01-01")
+    e = store.add(A, "t", expires_at=datetime.now(timezone.utc) + timedelta(days=1))
+    assert e.expires_at.endswith("+00:00")
+
+
+def test_derived_from_rules(store):
+    parent = store.add(A, "parent fact")
+    child = store.add(A, "summary of parent", kind="summary", derived_from=[parent.id])
+    assert child.derived_from == (parent.id,)
+    for bad in (["nothex"], [parent.id, parent.id], ["0" * 32], [5]):
+        with pytest.raises((InvalidEntryError, NotFoundError)):
+            store.add(A, "x", derived_from=bad)
+    with pytest.raises(InvalidEntryError):
+        store.add(A, "x", derived_from=["%032x" % i for i in range(101)])
+
+
+def test_derived_from_cannot_point_into_another_tenant(store):
+    other = store.add(Scope("other"), "their secret")
+    with pytest.raises(NotFoundError):
+        store.add(A, "link to theirs", derived_from=[other.id])
+    assert store.count(A) == 0

ragleap_memory-0.1.0/tests/test_durability.py

@@ -0,0 +1,103 @@
+import os
+import sqlite3
+import stat
+import threading
+
+import pytest
+
+from ragleap_memory import MemoryStoreError, NotFoundError, SQLiteStore
+from ragleap_security import AuditError, AuditLog, Scope
+
+A = Scope("acme")
+
+
+def test_data_survives_reopen(tmp_path):
+    p = tmp_path / "mem.db"
+    s = SQLiteStore(p)
+    e = s.add(A, "remember this across restarts", trust="owner", metadata={"k": 1})
+    s.close()
+    s2 = SQLiteStore(p)
+    assert s2.get(A, e.id) == e
+    assert [h.entry.id for h in s2.search(A, "restarts")] == [e.id]
+
+
+def test_database_file_is_private(tmp_path):
+    p = tmp_path / "mem.db"
+    SQLiteStore(p).add(A, "x y")
+    assert stat.S_IMODE(os.stat(p).st_mode) == 0o600
+
+
+def test_newer_schema_is_refused(tmp_path):
+    p = tmp_path / "mem.db"
+    SQLiteStore(p).close()
+    c = sqlite3.connect(p)
+    c.execute("PRAGMA user_version = 99")
+    c.commit()
+    c.close()
+    with pytest.raises(MemoryStoreError):
+        SQLiteStore(p)
+
+
+def test_threads_can_add_concurrently(tmp_path):
+    s = SQLiteStore(tmp_path / "mem.db")
+
+    def work(n):
+        for i in range(25):
+            s.add(Scope("acme", f"u{n}"), f"note {n} {i}")
+
+    ts = [threading.Thread(target=work, args=(n,)) for n in range(8)]
+    [t.start() for t in ts]
+    [t.join() for t in ts]
+    assert s.count(A) == 200
+    for n in range(8):
+        assert s.count(Scope("acme", f"u{n}")) == 25
+
+
+def test_a_failed_write_leaves_nothing_behind(store):
+    parent = store.add(A, "parent")
+    with pytest.raises(NotFoundError):
+        store.add(A, "child", derived_from=[parent.id, "0" * 32])  # second id does not exist
+    assert store.count(A) == 1
+
+
+def test_audit_log_records_operations_without_text(tmp_path):
+    audit = AuditLog(tmp_path / "audit.jsonl")
+    s = SQLiteStore(audit=audit)
+    e = s.add(A, "top secret plan", trust="owner")
+    n = s.supersede(A, e.id, "revised secret plan", trust="owner")
+    s.export(A)
+    s.forget(A, [n.id])
+    s.sweep_expired(A)
+    s.erase(A)
+    raw = open(audit.path).read()
+    assert "secret plan" not in raw
+    events = [__import__("json").loads(l)["event"] for l in raw.splitlines()]
+    assert events == ["memory.add", "memory.supersede", "memory.export", "memory.forget", "memory.sweep", "memory.erase"]
+    assert audit.verify().ok and all(__import__("json").loads(l)["scope"] == "tenant=acme" for l in raw.splitlines())
+
+
+def test_a_failing_audit_log_blocks_the_write(tmp_path):
+    class Broken:
+        def append(self, *a, **k):
+            raise AuditError("disk full")
+
+    s = SQLiteStore(audit=Broken())
+    with pytest.raises(AuditError):
+        s.add(A, "must not be stored unaudited")
+    assert s.count(A) == 0
+
+
+def test_a_failing_audit_log_blocks_erase_and_forget(tmp_path):
+    s = SQLiteStore()
+    e = s.add(A, "stays")
+
+    class Broken:
+        def append(self, *a, **k):
+            raise AuditError("disk full")
+
+    s._audit = Broken()
+    with pytest.raises(AuditError):
+        s.forget(A, [e.id])
+    with pytest.raises(AuditError):
+        s.erase(A)
+    assert s.count(A) == 1

ragleap_memory-0.1.0/tests/test_isolation.py

@@ -0,0 +1,107 @@
+import pytest
+
+from ragleap_memory import NotFoundError
+from ragleap_security import Scope
+
+A, B = Scope("acme"), Scope("globex")
+WORD = "quarterly forecast"
+
+
+@pytest.fixture
+def two(store):
+    a = store.add(A, f"acme {WORD}")
+    b = store.add(B, f"globex {WORD}")
+    return store, a, b
+
+
+def test_search_never_crosses_tenants(two):
+    store, a, b = two
+    assert [h.entry.id for h in store.search(A, WORD)] == [a.id]
+    assert [h.entry.id for h in store.search(B, WORD)] == [b.id]
+
+
+def test_get_across_tenants_looks_like_missing(two):
+    store, a, b = two
+    with pytest.raises(NotFoundError) as e1:
+        store.get(A, b.id)
+    with pytest.raises(NotFoundError) as e2:
+        store.get(A, "0" * 32)
+    assert str(e1.value) == str(e2.value)
+
+
+def test_count_export_are_per_tenant(two):
+    store, a, b = two
+    assert store.count(A) == 1 and store.count(B) == 1
+    assert [d["id"] for d in store.export(A)] == [a.id]
+    assert Scope("nobody").key and store.count(Scope("nobody")) == 0 and store.export(Scope("nobody")) == []
+
+
+def test_forget_cannot_delete_another_tenants_entry(two):
+    store, a, b = two
+    assert store.forget(A, [b.id]) == 0
+    assert store.count(B) == 1
+    assert store.forget(A, [a.id, b.id]) == 1  # only its own
+    assert store.count(A) == 0 and store.count(B) == 1
+
+
+def test_supersede_cannot_touch_another_tenants_entry(two):
+    store, a, b = two
+    with pytest.raises(NotFoundError):
+        store.supersede(A, b.id, "overwritten")
+    assert store.get(B, b.id).superseded_by is None
+    assert store.count(B) == 1
+
+
+def test_erase_and_sweep_stay_inside_the_tenant(two):
+    store, a, b = two
+    assert store.erase(A) == 1
+    assert store.count(A) == 0 and store.count(B) == 1
+    assert store.sweep_expired(A) == 0
+    assert [h.entry.id for h in store.search(B, WORD)] == [b.id]
+
+
+def test_narrow_scope_sees_only_its_own_subject(store):
+    alice, bob = Scope("acme", "alice"), Scope("acme", "bob")
+    ea = store.add(alice, f"alice {WORD}")
+    eb = store.add(bob, f"bob {WORD}")
+    assert [h.entry.id for h in store.search(alice, WORD)] == [ea.id]
+    assert [h.entry.id for h in store.search(bob, WORD)] == [eb.id]
+    with pytest.raises(NotFoundError):
+        store.get(alice, eb.id)
+    assert store.forget(alice, [eb.id]) == 0
+    assert store.erase(alice) == 1 and store.count(bob) == 1
+
+
+def test_tenant_wide_scope_sees_every_subject_in_its_tenant(store):
+    ea = store.add(Scope("acme", "alice"), f"alice {WORD}")
+    eb = store.add(Scope("acme", "bob"), f"bob {WORD}")
+    et = store.add(A, f"tenant-level {WORD}")
+    other = store.add(B, f"other {WORD}")
+    got = {h.entry.id for h in store.search(A, WORD, k=10)}
+    assert got == {ea.id, eb.id, et.id} and other.id not in got  # positive control plus isolation
+
+
+def test_subject_scope_does_not_see_tenant_level_entries(store):
+    tenant_level = store.add(A, f"tenant-level {WORD}")
+    alice = Scope("acme", "alice")
+    assert store.search(alice, WORD) == []
+    with pytest.raises(NotFoundError):
+        store.get(alice, tenant_level.id)
+
+
+def test_agent_and_session_parts_narrow_too(store):
+    s1 = Scope("acme", "alice", "bot", "s1")
+    s2 = Scope("acme", "alice", "bot", "s2")
+    e1 = store.add(s1, f"first {WORD}")
+    e2 = store.add(s2, f"second {WORD}")
+    assert [h.entry.id for h in store.search(s1, WORD)] == [e1.id]
+    assert {h.entry.id for h in store.search(Scope("acme", "alice", "bot"), WORD)} == {e1.id, e2.id}
+    assert store.search(Scope("acme", "alice", "other-bot"), WORD) == []
+
+
+def test_search_query_cannot_escape_the_scope(two):
+    store, a, b = two
+    for q in ['forecast" OR tenant:globex', "tenant:globex forecast", "forecast NOT acme", "* forecast", 'a" OR "b',
+              "forecast AND (globex OR acme)", "NEAR(forecast quarterly)", "text: forecast"]:
+        ids = {h.entry.id for h in store.search(A, q, k=10)}
+        assert b.id not in ids, q

ragleap_memory-0.1.0/tests/test_lifecycle.py

@@ -0,0 +1,103 @@
+import os
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+from ragleap_memory import InvalidEntryError, NotFoundError, SQLiteStore
+from ragleap_security import Scope
+
+A = Scope("acme")
+
+
+def test_supersede_links_old_and_new(store):
+    old = store.add(A, "owner phone is 111", kind="fact", trust="owner", importance=0.9)
+    new = store.supersede(A, old.id, "owner phone is 222", trust="owner")
+    assert new.derived_from == (old.id,) and new.kind == "fact" and new.importance == 0.9 and new.scope == A
+    assert store.get(A, old.id).superseded_by == new.id and store.get(A, new.id).superseded_by is None
+
+
+def test_supersede_overrides_and_keeps_the_old_entrys_scope(store):
+    old = store.add(Scope("acme", "alice"), "likes tea")
+    new = store.supersede(A, old.id, "likes coffee", kind="summary", importance=0.2)  # tenant-wide scope may do it
+    assert new.scope == Scope("acme", "alice") and new.kind == "summary" and new.importance == 0.2
+
+
+def test_narrower_scope_cannot_supersede_a_wider_entry(store):
+    wide = store.add(A, "tenant-level fact")
+    with pytest.raises(NotFoundError):
+        store.supersede(Scope("acme", "alice"), wide.id, "changed")
+
+
+def test_cannot_supersede_twice_or_with_bad_input(store):
+    old = store.add(A, "v1")
+    store.supersede(A, old.id, "v2")
+    with pytest.raises(InvalidEntryError):
+        store.supersede(A, old.id, "v3")
+    cur = store.add(A, "w1")
+    with pytest.raises(InvalidEntryError):
+        store.supersede(A, cur.id, "")
+    assert store.get(A, cur.id).superseded_by is None and store.count(A) == 3  # nothing half-written
+    with pytest.raises(NotFoundError):
+        store.supersede(A, "0" * 32, "x")
+
+
+def test_forget_counts_and_removes_from_search(store):
+    a, b = store.add(A, "remove me"), store.add(A, "keep me")
+    assert store.forget(A, [a.id]) == 1 and store.forget(A, [a.id]) == 0 and store.forget(A, []) == 0
+    assert store.search(A, "remove") == [] and [h.entry.id for h in store.search(A, "keep")] == [b.id]
+    for bad in (["nothex"], [5], ["0" * 32] * 1001):
+        with pytest.raises(InvalidEntryError):
+            store.forget(A, bad)
+
+
+def test_export_includes_everything_visible(store):
+    old = store.add(A, "old fact")
+    new = store.supersede(A, old.id, "new fact")
+    gone = store.add(A, "expired", expires_at=datetime(2000, 1, 1, tzinfo=timezone.utc))
+    ids = {d["id"] for d in store.export(A)}
+    assert ids == {old.id, new.id, gone.id}
+    d = next(x for x in store.export(A) if x["id"] == old.id)
+    assert d["scope"] == "tenant=acme" and d["superseded_by"] == new.id and d["text"] == "old fact"
+
+
+def test_sweep_expired_deletes_only_expired_in_scope(store):
+    now = datetime.now(timezone.utc)
+    s = SQLiteStore(clock=lambda: now)
+    s.add(A, "stale", expires_at=now - timedelta(seconds=1))
+    live = s.add(A, "fresh", expires_at=now + timedelta(days=1))
+    forever = s.add(A, "forever")
+    other_stale = s.add(Scope("globex"), "other stale", expires_at=now - timedelta(days=1))
+    assert s.sweep_expired(A) == 1
+    assert {d["id"] for d in s.export(A)} == {live.id, forever.id}
+    assert s.count(Scope("globex")) == 1 and s.get(Scope("globex"), other_stale.id)
+
+
+def test_erase_removes_text_from_the_file(tmp_path):
+    marker = "zyxwvmarkerqq"
+    path = tmp_path / "mem.db"
+    s = SQLiteStore(path)
+    for i in range(3):
+        s.add(A, f"keep this {i} and {marker} entry")
+    keep = s.add(Scope("globex"), "other tenant stays visible")
+
+    def raw():
+        return b"".join(open(str(path) + ext, "rb").read() for ext in ("", "-wal") if os.path.exists(str(path) + ext))
+
+    s.compact()
+    assert marker.encode() in raw()  # positive control: the text really is in the file
+    assert s.erase(A) == 3
+    assert marker.encode() not in raw()
+    assert [h.entry.id for h in s.search(Scope("globex"), "tenant")] == [keep.id]
+
+
+def test_forget_alone_may_leave_traces_until_compact(tmp_path):
+    # Documented limitation: forget() removes entries from queries at once, but the text can stay in
+    # the file's search index until compact() or erase() runs.
+    marker = "qwertymarkerzz"
+    path = tmp_path / "mem.db"
+    s = SQLiteStore(path)
+    e = s.add(A, f"entry with {marker}")
+    s.forget(A, [e.id])
+    s.compact()
+    raw = b"".join(open(str(path) + ext, "rb").read() for ext in ("", "-wal") if os.path.exists(str(path) + ext))
+    assert marker.encode() not in raw

ragleap_memory-0.1.0/tests/test_search.py

@@ -0,0 +1,111 @@
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+from ragleap_memory import InvalidEntryError
+from ragleap_security import LimitError, Scope
+
+A = Scope("acme")
+
+
+def test_relevance_order_and_scores(store):
+    best = store.add(A, "invoice invoice invoice payment terms")
+    ok = store.add(A, "the invoice was sent on Monday with many other words around it")
+    store.add(A, "completely unrelated gardening note")
+    hits = store.search(A, "invoice")
+    assert [h.entry.id for h in hits] == [best.id, ok.id]
+    assert hits[0].score >= hits[1].score > 0
+
+
+def test_any_word_may_match_and_unmatched_returns_nothing(store):
+    e = store.add(A, "alpha beta gamma")
+    assert [h.entry.id for h in store.search(A, "zzz gamma qqq")] == [e.id]
+    assert store.search(A, "zzz qqq") == []
+
+
+@pytest.mark.parametrize("q", ["", "   ", "!!! ???", '"""', "(", ")", "AND", "OR", "NOT", "*", "^", "-", ":"])
+def test_odd_queries_do_not_error(store, q):
+    store.add(A, "alpha beta")
+    store.search(A, q)
+
+
+def test_query_limits_and_types(store):
+    with pytest.raises(LimitError):
+        store.search(A, "x" * 1001)
+    with pytest.raises(InvalidEntryError):
+        store.search(A, 5)
+    store.search(A, "x " * 500)  # positive control: exactly 1000 bytes, 32-token cap applies
+
+
+@pytest.mark.parametrize("k", [0, -1, True, 1.5, "3", None])
+def test_bad_k_refused(store, k):
+    with pytest.raises(InvalidEntryError):
+        store.search(A, "x", k=k)
+
+
+def test_k_limits_results_and_is_capped(store):
+    for i in range(5):
+        store.add(A, f"common word {i}")
+    assert len(store.search(A, "common", k=2)) == 2
+    assert len(store.search(A, "common", k=10_000)) == 5  # under the store's cap of 50
+
+
+def test_store_wide_result_cap_applies_even_when_k_is_larger():
+    from ragleap_memory import SQLiteStore
+    s = SQLiteStore(max_results=3)
+    for i in range(6):
+        s.add(A, f"common word {i}")
+    assert len(s.search(A, "common", k=100)) == 3
+
+
+def test_kinds_filter(store):
+    f = store.add(A, "shared topic", kind="fact")
+    s = store.add(A, "shared topic", kind="summary")
+    assert {h.entry.id for h in store.search(A, "topic")} == {f.id, s.id}
+    assert [h.entry.id for h in store.search(A, "topic", kinds=["summary"])] == [s.id]
+    for bad in ([], ["note"], ["fact", "note"]):
+        with pytest.raises(InvalidEntryError):
+            store.search(A, "topic", kinds=bad)
+
+
+def test_min_trust_filter(store):
+    u = store.add(A, "shared topic", trust="untrusted")
+    m = store.add(A, "shared topic", trust="model")
+    o = store.add(A, "shared topic", trust="owner")
+    assert {h.entry.id for h in store.search(A, "topic")} == {u.id, m.id, o.id}
+    assert {h.entry.id for h in store.search(A, "topic", min_trust="model")} == {m.id, o.id}
+    assert [h.entry.id for h in store.search(A, "topic", min_trust="owner")] == [o.id]
+    with pytest.raises(InvalidEntryError):
+        store.search(A, "topic", min_trust="root")
+
+
+def test_search_results_carry_their_trust_label(store):
+    store.add(A, "labelled entry", trust="model")
+    assert store.search(A, "labelled")[0].entry.trust == "model"
+
+
+def test_expired_entries_are_hidden_unless_asked(store):
+    now = [datetime(2030, 1, 1, tzinfo=timezone.utc)]
+    from ragleap_memory import SQLiteStore
+    s = SQLiteStore(clock=lambda: now[0])
+    e = s.add(A, "short lived note", expires_at=now[0] + timedelta(hours=1))
+    assert [h.entry.id for h in s.search(A, "note")] == [e.id]
+    now[0] += timedelta(hours=1)  # exactly at the expiry instant: expired
+    assert s.search(A, "note") == []
+    assert [h.entry.id for h in s.search(A, "note", include_expired=True)] == [e.id]
+
+
+def test_superseded_entries_are_hidden_unless_asked(store):
+    old = store.add(A, "price is ten")
+    new = store.supersede(A, old.id, "price is twelve")
+    assert [h.entry.id for h in store.search(A, "price")] == [new.id]
+    assert {h.entry.id for h in store.search(A, "price", include_superseded=True)} == {old.id, new.id}
+
+
+@pytest.mark.parametrize("text,query", [
+    ("café au lait", "cafe"), ("Zürich Straße", "zurich"), ("नमस्ते दुनिया", "दुनिया"),
+    ("வணக்கம் உலகம்", "உலகம்"), ("مرحبا بالعالم", "بالعالم"), ("你好 世界", "世界"),
+])
+def test_non_english_text_is_searchable(store, text, query):
+    e = store.add(A, text)
+    assert [h.entry.id for h in store.search(A, query)] == [e.id]