mymemo 0.1.1__tar.gz

mymemo-0.1.1/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.pytest_cache/

mymemo-0.1.1/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: mymemo
+Version: 0.1.1
+Summary: Python SDK for OmniMem — Agent memory ledger on Turso/libSQL
+Project-URL: Homepage, https://github.com/OntarioLT/OmniMem
+Project-URL: Repository, https://github.com/OntarioLT/OmniMem
+Project-URL: Issues, https://github.com/OntarioLT/OmniMem/issues
+Author: OntarioLT
+License-Expression: MIT
+Keywords: agent,fts5,libsql,memory,rag,turso,vector
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: libsql>=0.1.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mymemo
+
+Python SDK for [MyMemo](https://github.com/OntarioLT/OmniMem) — Agent memory ledger on Turso/libSQL.
+
+## Install
+
+```bash
+pip install mymemo
+```
+
+## Quick Start
+
+```python
+from mymemo import MyMemoConfig, create_clients, MemoryStore, rank
+from mymemo.types import MemoryFactDraft, IncidentBase, SearchQuery
+import time
+
+# Configure
+config = MyMemoConfig(
+    routing={"primary": "wss://your-db.turso.io", "replica": "file:./local.db"}
+)
+
+# Connect
+clients = create_clients(config)
+store = MemoryStore(clients.writer, dimension=384)
+
+# Write memory
+meta = IncidentBase(scope="my-agent", incident_id="1", timestamp=int(time.time()))
+store.write(MemoryFactDraft(content="User prefers dark mode", category="user_preference"), meta)
+
+# Search
+results = store.get_candidates(SearchQuery(scope="my-agent", keyword="dark"))
+ranked = rank(results, SearchQuery(scope="my-agent"))
+```
+
+## Features
+
+- **Idempotent writes** — SHA256 deterministic IDs, no duplicates
+- **Hybrid search** — FTS5 full-text + vector similarity
+- **Adaptive ranking** — time decay, category-specific tuning
+- **GC** — automatic eviction of stale memories
+- **NaN defense** — rejects invalid vectors at write time
+- **Shared database** — compatible with the TypeScript core SDK
+
+## License
+
+MIT

mymemo-0.1.1/README.md

@@ -0,0 +1,47 @@
+# mymemo
+
+Python SDK for [MyMemo](https://github.com/OntarioLT/OmniMem) — Agent memory ledger on Turso/libSQL.
+
+## Install
+
+```bash
+pip install mymemo
+```
+
+## Quick Start
+
+```python
+from mymemo import MyMemoConfig, create_clients, MemoryStore, rank
+from mymemo.types import MemoryFactDraft, IncidentBase, SearchQuery
+import time
+
+# Configure
+config = MyMemoConfig(
+    routing={"primary": "wss://your-db.turso.io", "replica": "file:./local.db"}
+)
+
+# Connect
+clients = create_clients(config)
+store = MemoryStore(clients.writer, dimension=384)
+
+# Write memory
+meta = IncidentBase(scope="my-agent", incident_id="1", timestamp=int(time.time()))
+store.write(MemoryFactDraft(content="User prefers dark mode", category="user_preference"), meta)
+
+# Search
+results = store.get_candidates(SearchQuery(scope="my-agent", keyword="dark"))
+ranked = rank(results, SearchQuery(scope="my-agent"))
+```
+
+## Features
+
+- **Idempotent writes** — SHA256 deterministic IDs, no duplicates
+- **Hybrid search** — FTS5 full-text + vector similarity
+- **Adaptive ranking** — time decay, category-specific tuning
+- **GC** — automatic eviction of stale memories
+- **NaN defense** — rejects invalid vectors at write time
+- **Shared database** — compatible with the TypeScript core SDK
+
+## License
+
+MIT

mymemo-0.1.1/examples/demo.py

@@ -0,0 +1,58 @@
+"""MyMemo Python SDK Demo — 全流程演示"""
+
+import os
+import libsql as libsql
+from mymemo import MemoryStore, rank
+from mymemo.types import MemoryFactDraft, IncidentBase, SearchQuery
+import time
+
+DB_PATH = "file:./mymemo_demo.db"
+
+
+def main():
+    # 清理旧 demo 数据库
+    if os.path.exists("mymemo_demo.db"):
+        os.remove("mymemo_demo.db")
+
+    # 连接本地 libSQL 数据库
+    conn = libsql.connect(DB_PATH)
+    store = MemoryStore(conn, dimension=384)
+
+    # 写入多条记忆
+    meta = IncidentBase(scope="demo", incident_id="demo-1", timestamp=int(time.time()))
+    memories = [
+        ("用户喜欢深色模式", "user_preference"),
+        ("项目使用 TypeScript", "code_snippet"),
+        ("上周修复了登录 bug", "correction"),
+        ("TypeScript 类型系统很强大", "insight"),
+        ("用户在上海工作", "user_preference"),
+    ]
+    for content, category in memories:
+        store.write(MemoryFactDraft(content=content, category=category), meta)
+    print(f"✅ 写入 {len(memories)} 条记忆")
+
+    # 搜索
+    results = store.get_candidates(SearchQuery(scope="demo", keyword="TypeScript"))
+    print(f"\n🔍 搜索 'TypeScript' → {len(results)} 条结果")
+    for r in results:
+        print(f"   [{r.category}] {r.content}")
+
+    # 混合排序
+    ranked = rank(results, SearchQuery(scope="demo"))
+    print(f"\n📊 混合排序（文本+向量+时间衰减）:")
+    for r in ranked:
+        print(f"   score={r.final_score:.3f} | {r.content}")
+
+    # 归档
+    store.archive(results[0].id, "demo:已读", "user")
+    print(f"\n🗄️  归档: {results[0].content}")
+
+    # GC
+    archived = store.run_gc("demo")
+    print(f"\n🗑️  GC 淘汰 {archived} 条记忆")
+
+    print(f"\n📁 数据库文件: mymemo_demo.db")
+
+
+if __name__ == "__main__":
+    main()

mymemo-0.1.1/mymemo/__init__.py

@@ -0,0 +1,38 @@
+"""mymemo — Python SDK for MyMemo agent memory ledger."""
+
+from .config import MyMemoConfig
+from .client import MyMemoClients, create_clients
+from .store import MemoryStore
+from .recaller import rank
+from .types import (
+    CandidateMemory,
+    CheckpointIncident,
+    ExtractedFactIncident,
+    Incident,
+    IncidentBase,
+    MemoryFactDraft,
+    Message,
+    MessageBatchIncident,
+    RawEventIncident,
+    RankedMemory,
+    SearchQuery,
+)
+
+__all__ = [
+    "MyMemoConfig",
+    "MyMemoClients",
+    "create_clients",
+    "MemoryStore",
+    "rank",
+    "CandidateMemory",
+    "CheckpointIncident",
+    "ExtractedFactIncident",
+    "Incident",
+    "IncidentBase",
+    "MemoryFactDraft",
+    "Message",
+    "MessageBatchIncident",
+    "RawEventIncident",
+    "RankedMemory",
+    "SearchQuery",
+]

mymemo-0.1.1/mymemo/client.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import libsql as libsql
+
+from .config import MyMemoConfig
+
+
+class MyMemoClients:
+    def __init__(self, writer: libsql.Connection, reader: libsql.Connection):
+        self.writer = writer
+        self.reader = reader
+
+    def close(self):
+        self.writer.close()
+        self.reader.close()
+
+
+def create_clients(config: MyMemoConfig) -> MyMemoClients:
+    writer = libsql.connect(
+        config.routing.primary,
+        auth_token=config.routing.token,
+    )
+    reader = libsql.connect(
+        config.routing.replica,
+        sync_url=config.routing.primary,
+        sync_interval=config.sync_interval,
+    )
+    return OmniMemClients(writer, reader)

mymemo-0.1.1/mymemo/config.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class EmbedderConfig(BaseModel):
+    dimension: int = Field(384, pattern=r"^(384|768|1024|1536)$")
+    quantization: str = Field("f8", pattern=r"^(f8|f32)$")
+
+
+class RoutingConfig(BaseModel):
+    primary: str  # wss://xxx.turso.io
+    replica: str  # file:///path/to/local.db
+    token: str | None = None
+
+
+class CurationConfig(BaseModel):
+    default_hybrid_weights: dict[str, float] | None = None
+    min_final_score: float = Field(0.15, ge=0, le=1)
+
+
+class MyMemoConfig(BaseModel):
+    embedder: EmbedderConfig = EmbedderConfig()
+    routing: RoutingConfig
+    sync_interval: int = Field(5000, ge=1000, le=60000)
+    curation: CurationConfig = CurationConfig()

mymemo-0.1.1/mymemo/recaller.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import math
+
+from .types import CandidateMemory, RankedMemory, SearchQuery
+
+DEFAULT_CATEGORY_LAMBDA: dict[str, float] = {
+    "user_preference": 0.2,
+    "code_snippet": 0.6,
+    "correction": 0.5,
+    "insight": 0.3,
+    "ephemeral": 0.4,
+    "__default__": 0.4,
+}
+
+MIN_FINAL_SCORE = 0.15
+FTS_EXP_CLAMP = 1e-8
+
+
+def rank(candidates: list[CandidateMemory], query: SearchQuery) -> list[RankedMemory]:
+    results: list[RankedMemory] = []
+    for c in candidates:
+        lam = (
+            (query.category_lambda or {}).get(c.category)
+            or DEFAULT_CATEGORY_LAMBDA.get(c.category)
+            or DEFAULT_CATEGORY_LAMBDA["__default__"]
+        )
+
+        fts_score = math.exp(-lam * abs(c.raw_fts_score))
+        if fts_score < FTS_EXP_CLAMP:
+            fts_score = 0.0
+
+        vec_score = min(max(c.raw_vec_score, 0.0), 1.0)
+        decay_base = (query.decay_map or {}).get(c.category, 0.98)
+        decay_factor = math.pow(decay_base, max(0, c.days_since_retrieved))
+
+        w = query.hybrid_weights or {"vec": 0.6, "fts": 0.4}
+        final_score = (vec_score * w["vec"] + fts_score * w["fts"]) * decay_factor * c.weight
+
+        if final_score >= MIN_FINAL_SCORE:
+            results.append(
+                RankedMemory(
+                    id=c.id,
+                    content=c.content,
+                    category=c.category,
+                    weight=c.weight,
+                    version=c.version,
+                    preserve_reason=c.preserve_reason,
+                    successful_recall_count=c.successful_recall_count,
+                    raw_fts_score=c.raw_fts_score,
+                    raw_vec_score=c.raw_vec_score,
+                    days_since_retrieved=c.days_since_retrieved,
+                    fts_score=fts_score,
+                    vec_score=vec_score,
+                    final_score=final_score,
+                    decay_factor=decay_factor,
+                )
+            )
+
+    results.sort(key=lambda r: r.final_score, reverse=True)
+    return results

mymemo-0.1.1/mymemo/store.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import time
+from typing import Any
+
+import libsql as libsql
+
+from .types import (
+    CandidateMemory,
+    IncidentBase,
+    MemoryFactDraft,
+    SearchQuery,
+)
+
+
+DDL_TEMPLATES = [
+    """CREATE TABLE IF NOT EXISTS memories (
+        id TEXT PRIMARY KEY,
+        content TEXT NOT NULL,
+        embedding F8_BLOB({dim}),
+        category TEXT NOT NULL,
+        weight REAL DEFAULT 1.0,
+        version INTEGER DEFAULT 1,
+        status TEXT DEFAULT 'active',
+        preserve_reason TEXT CHECK (preserve_reason IN (
+            'user_locked', 'correction', 'core_rule', 'system_proven', 'admin_override'
+        )),
+        preserved_by TEXT,
+        successful_recall_count INTEGER DEFAULT 0,
+        created_at INTEGER NOT NULL
+            CHECK (created_at > 1000000000 AND created_at < 2000000000),
+        last_retrieved INTEGER,
+        retrieval_count INTEGER DEFAULT 0,
+        scope TEXT NOT NULL,
+        incident_id TEXT,
+        metadata JSON
+    )""",
+    "CREATE INDEX IF NOT EXISTS idx_memories_scope_status ON memories(scope, status, category)",
+    """CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+        content, category,
+        content='memories', content_rowid='rowid',
+        tokenize='unicode61 remove_diacritics 1'
+    )""",
+    """CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+        INSERT INTO memories_fts(rowid, content, category) VALUES (new.rowid, new.content, new.category);
+    END""",
+    """CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+        INSERT INTO memories_fts(memories_fts, rowid, content, category) VALUES ('delete', old.rowid, old.content, old.category);
+        INSERT INTO memories_fts(rowid, content, category) VALUES (new.rowid, new.content, new.category);
+    END""",
+    """CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+        INSERT INTO memories_fts(memories_fts, rowid, content, category) VALUES ('delete', old.rowid, old.content, old.category);
+    END""",
+    """CREATE TABLE IF NOT EXISTS tasks (
+        id TEXT PRIMARY KEY,
+        scope TEXT NOT NULL,
+        description TEXT,
+        status TEXT,
+        complexity_score REAL DEFAULT 1.0,
+        tokens_used INTEGER,
+        errors INTEGER,
+        created_at INTEGER NOT NULL
+    )""",
+    """CREATE TABLE IF NOT EXISTS memory_task_attributions (
+        memory_id TEXT,
+        task_id TEXT,
+        similarity REAL,
+        credit REAL,
+        PRIMARY KEY (memory_id, task_id),
+        FOREIGN KEY (memory_id) REFERENCES memories(id),
+        FOREIGN KEY (task_id) REFERENCES tasks(id)
+    )""",
+]
+
+
+class MemoryStore:
+    def __init__(self, conn: libsql.Connection, dimension: int = 384):
+        self.conn = conn
+        self.dimension = dimension
+        self._init_schema()
+
+    def _init_schema(self):
+        for ddl in DDL_TEMPLATES:
+            self.conn.execute(ddl.format(dim=self.dimension))
+        self.conn.commit()
+
+    def _sha256(self, data: str) -> str:
+        return hashlib.sha256(data.encode()).hexdigest()
+
+    def write(self, draft: MemoryFactDraft, meta: IncidentBase) -> str:
+        # L2 normalize embedding if present
+        raw_vector: list[float] = getattr(draft, "embedding", []) or []
+        normalized: list[float] = []
+        if raw_vector:
+            norm = math.sqrt(sum(v * v for v in raw_vector))
+            normalized = [v / norm for v in raw_vector]
+            if not all(math.isfinite(v) for v in normalized):
+                raise ValueError(
+                    f"[OmniMem] Invalid vector (NaN/Infinity) for incident {meta.incident_id}"
+                )
+
+        # Deterministic ID
+        content_hash = self._sha256(draft.content)
+        memory_id = self._sha256(f"{meta.scope}|{meta.incident_id}|{content_hash}")
+
+        # Idempotent write
+        self.conn.execute(
+            """INSERT OR IGNORE INTO memories
+               (id, content, embedding, category, scope, incident_id, created_at,
+                weight, version, preserve_reason, successful_recall_count)
+               VALUES (?, ?, vector8(?), ?, ?, ?, strftime('%s','now'), ?, ?, ?, ?)""",
+            tuple([
+                memory_id,
+                draft.content,
+                json.dumps(normalized),
+                draft.category,
+                meta.scope,
+                meta.incident_id,
+                draft.weight,
+                draft.version,
+                draft.preserve_reason,
+                draft.successful_recall_count,
+            ]),
+        )
+        self.conn.commit()
+        return memory_id
+
+    def archive(self, memory_id: str, reason: str, by: str) -> None:
+        self.conn.execute(
+            """UPDATE memories SET status='archived', preserved_by=?,
+               metadata=json_set(COALESCE(metadata,'{}'),'$.archive_reason',?)
+               WHERE id=?""",
+            (by, reason, memory_id),
+        )
+        self.conn.commit()
+
+    def archive_batch(self, memory_ids: list[str], reason: str, by: str) -> None:
+        if not memory_ids:
+            return
+        placeholders = ",".join(["?"] * len(memory_ids))
+        sql = (
+            "UPDATE memories SET status='archived', preserved_by=?,"
+            "metadata=json_set(COALESCE(metadata,'{}'),'$.archive_reason',?)"
+            f"WHERE id IN ({placeholders})"
+        )
+        self.conn.execute(sql, tuple([by, reason, *memory_ids]))
+        self.conn.commit()
+
+    def get_candidates(self, query: SearchQuery, max_candidates: int = 200) -> list[CandidateMemory]:
+        keyword = query.keyword or "*"
+        vector_json = json.dumps(query.vector or [])
+
+        rows = self.conn.execute(
+            """WITH fts_candidates AS (
+                SELECT m.rowid, m.id, m.content, m.category, m.weight, m.version,
+                       m.last_retrieved, m.created_at,
+                       bm25(memories_fts) as raw_fts_score
+                FROM memories m
+                JOIN memories_fts ON m.rowid = memories_fts.rowid
+                WHERE m.scope = ? AND m.status = 'active' AND memories_fts MATCH ?
+                ORDER BY bm25(memories_fts) ASC
+                LIMIT ?
+            )
+            SELECT fc.id, fc.content, fc.category, fc.weight, fc.version,
+                   fc.raw_fts_score,
+                   (1.0 - vector_distance_cos(m.embedding, vector8(?))) as raw_vec_score,
+                   (strftime('%s','now') - fc.last_retrieved) / 86400.0 as days_since_retrieved
+            FROM fts_candidates fc
+            JOIN memories m ON fc.id = m.id""",
+            (query.scope, keyword, max_candidates, vector_json),
+        ).fetchall()
+
+        return [
+            CandidateMemory(
+                id=row[0],
+                content=row[1],
+                category=row[2],
+                weight=row[3],
+                version=row[4],
+                preserve_reason=None,
+                successful_recall_count=0,
+                raw_fts_score=row[5],
+                raw_vec_score=row[6] or 0.0,
+                days_since_retrieved=row[7] or 0.0,
+            )
+            for row in rows
+        ]
+
+    def run_gc(self, scope: str) -> int:
+        cursor = self.conn.execute(
+            """UPDATE memories SET status='archived', preserved_by='evolver:gc'
+               WHERE scope = ? AND status='active' AND preserve_reason IS NULL
+                 AND (strftime('%s','now') - created_at) > 86400
+                 AND (
+                   (retrieval_count = 0 AND (strftime('%s','now') - created_at) > 2592000)
+                   OR (retrieval_count > 10 AND weight < 0.2)
+                   OR (version < 5 AND retrieval_count = 0 AND (strftime('%s','now') - created_at) > 7776000)
+                 )""",
+            (scope,),
+        )
+        self.conn.commit()
+        return cursor.rowcount

mymemo-0.1.1/mymemo/types.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+@dataclass
+class IncidentBase:
+    scope: str
+    incident_id: str
+    timestamp: int
+
+
+@dataclass
+class Message:
+    role: Literal["user", "assistant", "system"]
+    content: str
+
+
+@dataclass
+class MessageBatchIncident(IncidentBase):
+    type: Literal["message_batch"] = "message_batch"
+    messages: list[Message] = field(default_factory=list)
+    session_context: dict | None = None
+
+
+@dataclass
+class CheckpointIncident(IncidentBase):
+    type: Literal["checkpoint"] = "checkpoint"
+    level: str = "auto"
+    content: str = ""
+
+
+@dataclass
+class ExtractedFactIncident(IncidentBase):
+    type: Literal["extracted_fact"] = "extracted_fact"
+    statement: str = ""
+    confidence: float = 0.0
+
+
+@dataclass
+class RawEventIncident(IncidentBase):
+    type: Literal["raw_event"] = "raw_event"
+    payload: dict = field(default_factory=dict)
+
+
+Incident = MessageBatchIncident | CheckpointIncident | ExtractedFactIncident | RawEventIncident
+
+
+@dataclass
+class SearchQuery:
+    scope: str
+    keyword: str | None = None
+    vector: list[float] | None = None
+    category: list[str] | None = None
+    limit: int = 20
+    freshness: Literal["eventual", "strong"] = "eventual"
+    decay_map: dict[str, float] | None = None
+    hybrid_weights: dict[str, float] | None = None
+    category_lambda: dict[str, float] | None = None
+
+
+@dataclass
+class CandidateMemory:
+    id: str
+    content: str
+    category: str
+    weight: float
+    version: int
+    preserve_reason: str | None
+    successful_recall_count: int
+    raw_fts_score: float
+    raw_vec_score: float
+    days_since_retrieved: float
+
+
+@dataclass
+class RankedMemory(CandidateMemory):
+    fts_score: float = 0.0
+    vec_score: float = 0.0
+    final_score: float = 0.0
+    decay_factor: float = 1.0
+
+
+@dataclass
+class MemoryFactDraft:
+    content: str
+    category: str
+    weight: float = 1.0
+    version: int = 1
+    preserve_reason: str | None = None
+    successful_recall_count: int = 0

mymemo-0.1.1/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mymemo"
+version = "0.1.1"
+description = "Python SDK for OmniMem — Agent memory ledger on Turso/libSQL"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "OntarioLT" }]
+keywords = ["agent", "memory", "rag", "turso", "libsql", "fts5", "vector"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "libsql>=0.1.0",
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/OntarioLT/OmniMem"
+Repository = "https://github.com/OntarioLT/OmniMem"
+Issues = "https://github.com/OntarioLT/OmniMem/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+addopts = "-v"

mymemo-0.1.1/tests/test_store.py

@@ -0,0 +1,116 @@
+import hashlib
+import math
+import time
+
+import libsql as libsql
+import pytest
+
+from mymemo.store import MemoryStore
+from mymemo.types import (
+    IncidentBase,
+    MemoryFactDraft,
+    SearchQuery,
+    CandidateMemory,
+)
+from mymemo.recaller import rank
+
+
+@pytest.fixture
+def store():
+    conn = libsql.connect(":memory:")
+    return MemoryStore(conn, dimension=384)
+
+
+@pytest.fixture
+def store_with_data(store: MemoryStore):
+    meta = IncidentBase(scope="test", incident_id="inc1", timestamp=int(time.time()))
+    store.write(MemoryFactDraft(content="TypeScript is great", category="insight"), meta)
+    store.write(MemoryFactDraft(content="Python is also great", category="insight"), meta)
+    return store
+
+
+class TestMemoryStore:
+    def test_idempotent_writes(self, store: MemoryStore):
+        """相同内容 + 相同 scope/incident → 返回相同 SHA256 ID"""
+        meta = IncidentBase(scope="s", incident_id="i1", timestamp=1000000001)
+        id1 = store.write(MemoryFactDraft(content="hello", category="a"), meta)
+        id2 = store.write(MemoryFactDraft(content="hello", category="a"), meta)
+        assert id1 == id2
+
+    def test_different_content_different_id(self, store: MemoryStore):
+        """不同内容产生不同的确定性 ID"""
+        meta = IncidentBase(scope="s", incident_id="i1", timestamp=1000000001)
+        id1 = store.write(MemoryFactDraft(content="a", category="x"), meta)
+        id2 = store.write(MemoryFactDraft(content="b", category="x"), meta)
+        assert id1 != id2
+
+    def test_soft_archive(self, store: MemoryStore):
+        """软删除 — 设置 status=archived，不物理删除"""
+        meta = IncidentBase(scope="s", incident_id="i1", timestamp=1000000001)
+        mid = store.write(MemoryFactDraft(content="x", category="c"), meta)
+        store.archive(mid, "test", "user")
+        row = store.conn.execute("SELECT status FROM memories WHERE id=?", (mid,)).fetchone()
+        assert row[0] == "archived"
+
+    def test_batch_archive(self, store: MemoryStore):
+        """批量归档 — 单次查询处理多条记忆"""
+        meta = IncidentBase(scope="s", incident_id="i1", timestamp=1000000001)
+        id1 = store.write(MemoryFactDraft(content="a", category="c"), meta)
+        id2 = store.write(MemoryFactDraft(content="b", category="c"), meta)
+        store.archive_batch([id1, id2], "batch", "sys")
+        rows = store.conn.execute("SELECT status FROM memories WHERE id IN (?,?)", (id1, id2)).fetchall()
+        assert all(r[0] == "archived" for r in rows)
+
+    def test_hybrid_search(self, store_with_data: MemoryStore):
+        """FTS5 全文搜索返回匹配结果"""
+        results = store_with_data.get_candidates(SearchQuery(scope="test", keyword="TypeScript"))
+        assert len(results) >= 1
+        assert any("TypeScript" in r.content for r in results)
+
+    def test_empty_search_result(self, store: MemoryStore):
+        """无匹配时返回空列表"""
+        results = store.get_candidates(SearchQuery(scope="nonexistent", keyword="x"))
+        assert results == []
+
+    def test_gc_archives_eligible_memories(self, store: MemoryStore):
+        """GC 淘汰过期、未检索、低权重的记忆"""
+        store.conn.execute(
+            "INSERT INTO memories (id, content, category, scope, incident_id, created_at, retrieval_count, weight, version) "
+            "VALUES ('gc1', 'old', 'ephemeral', 'gc_scope', 'inc', 1000000001, 0, 1.0, 1)"
+        )
+        store.conn.commit()
+        count = store.run_gc("gc_scope")
+        assert count >= 1
+
+    def test_nan_vector_rejected(self, store: MemoryStore):
+        """NaN/Infinity 向量被拒绝，防止脏数据入库"""
+        meta = IncidentBase(scope="s", incident_id="i1", timestamp=1000000001)
+        draft = MemoryFactDraft(content="x", category="c")
+        draft.embedding = [float("nan"), 0.0, 0.0]  # type: ignore
+        with pytest.raises(ValueError, match="NaN/Infinity"):
+            store.write(draft, meta)
+
+
+class TestAdaptiveRecaller:
+    def test_ranking_by_hybrid_score(self):
+        """按文本+向量混合评分排序"""
+        c1 = CandidateMemory("1", "a", "insight", 1.0, 1, None, 0, -5.0, 0.3, 0)
+        c2 = CandidateMemory("2", "b", "insight", 1.0, 1, None, 0, -0.5, 0.9, 0)
+        q = SearchQuery(scope="test")
+        ranked = rank([c1, c2], q)
+        assert ranked[0].id == "2"
+
+    def test_filters_irrelevant_results(self):
+        """低分结果被过滤（score < 0.15）"""
+        c = CandidateMemory("1", "a", "insight", 1.0, 1, None, 0, -100, 0.01, 0)
+        q = SearchQuery(scope="test")
+        ranked = rank([c], q)
+        assert len(ranked) == 0
+
+    def test_time_decay(self):
+        """时间衰减 — 新记忆排名高于旧记忆"""
+        c_fresh = CandidateMemory("f", "a", "insight", 1.0, 1, None, 0, -0.1, 0.9, 0)
+        c_old = CandidateMemory("o", "a", "insight", 1.0, 1, None, 0, -0.1, 0.9, 30)
+        q = SearchQuery(scope="test")
+        ranked = rank([c_fresh, c_old], q)
+        assert ranked[0].id == "f"