snipara-memory 0.1.0__py3-none-any.whl

snipara_memory/__init__.py

@@ -0,0 +1,67 @@
+"""Public package exports for snipara-memory."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .adapters import InMemoryMemoryStore, JsonFileMemoryStore, get_default_store_path
+from .api import create_app
+from .domain import (
+    CompactionResult,
+    Contradiction,
+    ContradictionResolution,
+    ContradictionStatus,
+    GraveyardEntry,
+    GraveyardReason,
+    Memory,
+    MemoryScope,
+    MemoryService,
+    MemoryStatus,
+    MemoryTier,
+    MemoryType,
+    Namespace,
+    NamespaceType,
+    RecallMatch,
+    RecallQuery,
+    ResolveContradictionRequest,
+    SessionMemoryBundle,
+    StoreMemoryRequest,
+    calculate_confidence_decay,
+    classify_memory_tier,
+)
+from .ports import CacheStore, EmbeddingsProvider, MemoryStore
+
+try:
+    __version__ = version("snipara-memory")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+__all__ = [
+    "CacheStore",
+    "CompactionResult",
+    "Contradiction",
+    "ContradictionResolution",
+    "ContradictionStatus",
+    "EmbeddingsProvider",
+    "GraveyardEntry",
+    "GraveyardReason",
+    "InMemoryMemoryStore",
+    "JsonFileMemoryStore",
+    "Memory",
+    "MemoryScope",
+    "MemoryService",
+    "MemoryStatus",
+    "MemoryStore",
+    "MemoryTier",
+    "MemoryType",
+    "Namespace",
+    "NamespaceType",
+    "RecallMatch",
+    "RecallQuery",
+    "ResolveContradictionRequest",
+    "SessionMemoryBundle",
+    "StoreMemoryRequest",
+    "__version__",
+    "calculate_confidence_decay",
+    "classify_memory_tier",
+    "create_app",
+    "get_default_store_path",
+]

snipara_memory/__main__.py

@@ -0,0 +1,7 @@
+"""Module entrypoint for the standalone CLI."""
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

snipara_memory/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Adapter exports for snipara-memory."""
+
+from .in_memory_store import InMemoryMemoryStore
+from .json_file_store import JsonFileMemoryStore, get_default_store_path
+
+__all__ = ["InMemoryMemoryStore", "JsonFileMemoryStore", "get_default_store_path"]

snipara_memory/adapters/in_memory_store.py

@@ -0,0 +1,212 @@
+"""In-memory adapter for local testing of the standalone memory engine."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+
+from ..domain import Contradiction, GraveyardEntry, Memory, MemoryStatus, MemoryTier, MemoryType, RecallMatch, RecallQuery
+
+
+class InMemoryMemoryStore:
+    """Simple in-memory store that implements the memory service contract."""
+
+    def __init__(self) -> None:
+        self._memories: dict[str, Memory] = {}
+        self._graveyard: dict[str, GraveyardEntry] = {}
+        self._contradictions: dict[str, Contradiction] = {}
+        self._embeddings: dict[str, list[float]] = {}
+
+    async def create_memory(
+        self,
+        memory: Memory,
+        *,
+        embedding: Sequence[float] | None = None,
+    ) -> Memory:
+        self._memories[memory.id] = memory
+        if embedding is not None:
+            self._embeddings[memory.id] = list(embedding)
+        return memory
+
+    async def create_memories(
+        self,
+        memories: Sequence[Memory],
+        *,
+        embeddings: Sequence[Sequence[float] | None] | None = None,
+    ) -> list[Memory]:
+        created: list[Memory] = []
+        embeddings = embeddings or [None] * len(memories)
+
+        for memory, embedding in zip(memories, embeddings, strict=False):
+            created.append(await self.create_memory(memory, embedding=embedding))
+
+        return created
+
+    async def search(
+        self,
+        query: RecallQuery,
+        *,
+        query_embedding: Sequence[float] | None = None,
+    ) -> list[RecallMatch]:
+        candidates = self._filter_memories(
+            query.namespace_id,
+            include_archived=query.include_archived,
+            types=query.types,
+            tiers=query.tiers,
+            tags=query.tags,
+        )
+        matches = [
+            RecallMatch(memory=memory, score=self._score(memory, query.query, query_embedding))
+            for memory in candidates
+        ]
+        matches = [match for match in matches if match.score > 0]
+        matches.sort(
+            key=lambda match: (
+                match.score,
+                match.memory.confidence,
+                match.memory.last_accessed_at or match.memory.created_at,
+            ),
+            reverse=True,
+        )
+        return matches[: query.limit]
+
+    async def list_memories(
+        self,
+        namespace_id: str,
+        *,
+        statuses: Sequence[MemoryStatus] | None = None,
+        tiers: Sequence[MemoryTier] | None = None,
+        types: Sequence[MemoryType] | None = None,
+        limit: int | None = None,
+    ) -> list[Memory]:
+        memories = [
+            memory
+            for memory in self._memories.values()
+            if memory.namespace_id == namespace_id
+            and (not statuses or memory.status in statuses)
+            and (not tiers or memory.tier in tiers)
+            and (not types or memory.type in types)
+        ]
+        memories.sort(
+            key=lambda memory: memory.last_accessed_at or memory.created_at,
+            reverse=True,
+        )
+        if limit is not None:
+            return memories[:limit]
+        return memories
+
+    async def get_memory(self, memory_id: str) -> Memory | None:
+        return self._memories.get(memory_id)
+
+    async def update_memory(self, memory: Memory) -> Memory:
+        self._memories[memory.id] = memory
+        return memory
+
+    async def delete_memory(self, memory_id: str) -> None:
+        self._memories.pop(memory_id, None)
+        self._embeddings.pop(memory_id, None)
+
+    async def create_graveyard_entry(self, entry: GraveyardEntry) -> GraveyardEntry:
+        self._graveyard[entry.id] = entry
+        return entry
+
+    async def get_graveyard_entry(self, entry_id: str) -> GraveyardEntry | None:
+        return self._graveyard.get(entry_id)
+
+    async def save_contradiction(self, contradiction: Contradiction) -> Contradiction:
+        self._contradictions[contradiction.id] = contradiction
+        return contradiction
+
+    async def get_contradiction(self, contradiction_id: str) -> Contradiction | None:
+        return self._contradictions.get(contradiction_id)
+
+    async def list_contradiction_candidates(
+        self,
+        namespace_id: str,
+        *,
+        similarity_threshold: float,
+    ) -> list[tuple[Memory, Memory, float]]:
+        memories = self._filter_memories(namespace_id, include_archived=False)
+        candidates: list[tuple[Memory, Memory, float]] = []
+
+        for index, memory_a in enumerate(memories):
+            for memory_b in memories[index + 1 :]:
+                if memory_a.content_hash == memory_b.content_hash:
+                    continue
+                similarity = self._pair_similarity(memory_a, memory_b)
+                if similarity >= similarity_threshold:
+                    candidates.append((memory_a, memory_b, similarity))
+
+        return candidates
+
+    def _filter_memories(
+        self,
+        namespace_id: str,
+        *,
+        include_archived: bool,
+        types: Sequence[MemoryType] | None = None,
+        tiers: Sequence[MemoryTier] | None = None,
+        tags: Sequence[str] | None = None,
+    ) -> list[Memory]:
+        allowed_statuses = {MemoryStatus.ACTIVE}
+        if include_archived:
+            allowed_statuses.add(MemoryStatus.ARCHIVED)
+
+        return [
+            memory
+            for memory in self._memories.values()
+            if memory.namespace_id == namespace_id
+            and memory.status in allowed_statuses
+            and memory.status is not MemoryStatus.GRAVEYARD
+            and (not types or memory.type in types)
+            and (not tiers or memory.tier in tiers)
+            and (not tags or set(tags).issubset(set(memory.tags)))
+        ]
+
+    def _score(
+        self,
+        memory: Memory,
+        query: str,
+        query_embedding: Sequence[float] | None,
+    ) -> float:
+        if query_embedding is not None and memory.id in self._embeddings:
+            return self._cosine_similarity(query_embedding, self._embeddings[memory.id])
+
+        query_terms = self._tokenize(query)
+        memory_terms = self._tokenize(memory.content)
+        if not query_terms or not memory_terms:
+            return 0.0
+
+        overlap = len(query_terms & memory_terms)
+        return overlap / max(len(query_terms), 1)
+
+    def _pair_similarity(self, memory_a: Memory, memory_b: Memory) -> float:
+        embedding_a = self._embeddings.get(memory_a.id)
+        embedding_b = self._embeddings.get(memory_b.id)
+        if embedding_a is not None and embedding_b is not None:
+            return self._cosine_similarity(embedding_a, embedding_b)
+
+        terms_a = self._tokenize(memory_a.content)
+        terms_b = self._tokenize(memory_b.content)
+        union = terms_a | terms_b
+        if not union:
+            return 0.0
+        return len(terms_a & terms_b) / len(union)
+
+    def _cosine_similarity(
+        self,
+        left: Sequence[float],
+        right: Sequence[float],
+    ) -> float:
+        if len(left) != len(right) or not left:
+            return 0.0
+
+        numerator = sum(a * b for a, b in zip(left, right, strict=False))
+        left_norm = math.sqrt(sum(value * value for value in left))
+        right_norm = math.sqrt(sum(value * value for value in right))
+        if left_norm == 0 or right_norm == 0:
+            return 0.0
+        return numerator / (left_norm * right_norm)
+
+    def _tokenize(self, text: str) -> set[str]:
+        return {token for token in text.lower().split() if token}

snipara_memory/adapters/json_file_store.py

@@ -0,0 +1,251 @@
+"""Persistent JSON-backed adapter for local standalone usage."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from datetime import date, datetime
+from pathlib import Path
+from typing import Any
+
+from ..domain import (
+    Contradiction,
+    ContradictionResolution,
+    ContradictionStatus,
+    GraveyardEntry,
+    GraveyardReason,
+    Memory,
+    MemoryScope,
+    MemoryStatus,
+    MemoryTier,
+    MemoryType,
+)
+from .in_memory_store import InMemoryMemoryStore
+
+
+DEFAULT_STORE_PATH = Path.home() / ".snipara-memory" / "store.json"
+
+
+def get_default_store_path() -> Path:
+    """Return the default persistent store path."""
+    return DEFAULT_STORE_PATH
+
+
+class JsonFileMemoryStore(InMemoryMemoryStore):
+    """Persist the in-memory adapter state to a local JSON file."""
+
+    def __init__(self, path: str | Path | None = None) -> None:
+        super().__init__()
+        self._path = Path(path or DEFAULT_STORE_PATH).expanduser()
+        self._load_state()
+
+    async def create_memory(
+        self,
+        memory: Memory,
+        *,
+        embedding: list[float] | tuple[float, ...] | None = None,
+    ) -> Memory:
+        created = await super().create_memory(memory, embedding=embedding)
+        self._write_state()
+        return created
+
+    async def create_memories(
+        self,
+        memories,
+        *,
+        embeddings=None,
+    ) -> list[Memory]:
+        created = await super().create_memories(memories, embeddings=embeddings)
+        self._write_state()
+        return created
+
+    async def update_memory(self, memory: Memory) -> Memory:
+        updated = await super().update_memory(memory)
+        self._write_state()
+        return updated
+
+    async def delete_memory(self, memory_id: str) -> None:
+        await super().delete_memory(memory_id)
+        self._write_state()
+
+    async def create_graveyard_entry(self, entry: GraveyardEntry) -> GraveyardEntry:
+        stored = await super().create_graveyard_entry(entry)
+        self._write_state()
+        return stored
+
+    async def save_contradiction(self, contradiction: Contradiction) -> Contradiction:
+        stored = await super().save_contradiction(contradiction)
+        self._write_state()
+        return stored
+
+    def _load_state(self) -> None:
+        if not self._path.exists():
+            return
+
+        data = json.loads(self._path.read_text(encoding="utf-8"))
+        self._memories = {
+            item["id"]: _memory_from_dict(item)
+            for item in data.get("memories", [])
+        }
+        self._graveyard = {
+            item["id"]: _graveyard_entry_from_dict(item)
+            for item in data.get("graveyard", [])
+        }
+        self._contradictions = {
+            item["id"]: _contradiction_from_dict(item)
+            for item in data.get("contradictions", [])
+        }
+        self._embeddings = {
+            memory_id: [float(value) for value in embedding]
+            for memory_id, embedding in data.get("embeddings", {}).items()
+        }
+
+    def _write_state(self) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "version": 1,
+            "memories": [_serialize(asdict(memory)) for memory in self._memories.values()],
+            "graveyard": [_serialize(asdict(entry)) for entry in self._graveyard.values()],
+            "contradictions": [
+                _serialize(asdict(contradiction))
+                for contradiction in self._contradictions.values()
+            ],
+            "embeddings": self._embeddings,
+        }
+        tmp_path = self._path.with_suffix(".tmp")
+        tmp_path.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+        tmp_path.replace(self._path)
+
+
+def _serialize(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {key: _serialize(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_serialize(item) for item in value]
+    if isinstance(value, tuple):
+        return [_serialize(item) for item in value]
+    if isinstance(value, (MemoryType, MemoryScope, MemoryTier, MemoryStatus)):
+        return value.value
+    if isinstance(value, (GraveyardReason, ContradictionStatus, ContradictionResolution)):
+        return value.value
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    return value
+
+
+def _parse_datetime(value: str | None) -> datetime | None:
+    if value is None:
+        return None
+    return datetime.fromisoformat(value)
+
+
+def _parse_date(value: str | None) -> date | None:
+    if value is None:
+        return None
+    return date.fromisoformat(value)
+
+
+def _memory_from_dict(data: dict[str, Any]) -> Memory:
+    return Memory(
+        id=data["id"],
+        namespace_id=data["namespace_id"],
+        content=data["content"],
+        content_hash=data["content_hash"],
+        title=data.get("title"),
+        type=MemoryType(data.get("type", MemoryType.FACT.value)),
+        scope=MemoryScope(data.get("scope", MemoryScope.PROJECT.value)),
+        category=data.get("category"),
+        source=data.get("source"),
+        tags=list(data.get("tags", [])),
+        metadata=dict(data.get("metadata", {})),
+        confidence=float(data.get("confidence", 1.0)),
+        relevance_boost=float(data.get("relevance_boost", 1.0)),
+        access_count=int(data.get("access_count", 0)),
+        last_accessed_at=_parse_datetime(data.get("last_accessed_at")),
+        tier=MemoryTier(data.get("tier", MemoryTier.ARCHIVE.value)),
+        status=MemoryStatus(data.get("status", MemoryStatus.ACTIVE.value)),
+        related_memory_ids=list(data.get("related_memory_ids", [])),
+        document_refs=list(data.get("document_refs", [])),
+        invalid_document_refs=list(data.get("invalid_document_refs", [])),
+        expires_at=_parse_datetime(data.get("expires_at")),
+        journal_date=_parse_date(data.get("journal_date")),
+        contradiction_count=int(data.get("contradiction_count", 0)),
+        superseded_by_id=data.get("superseded_by_id"),
+        restored_from_graveyard_id=data.get("restored_from_graveyard_id"),
+        promoted_at=_parse_datetime(data.get("promoted_at")),
+        promoted_by=data.get("promoted_by"),
+        buried_at=_parse_datetime(data.get("buried_at")),
+        buried_reason=(
+            GraveyardReason(data["buried_reason"])
+            if data.get("buried_reason") is not None
+            else None
+        ),
+        created_at=_parse_datetime(data.get("created_at")),
+        updated_at=_parse_datetime(data.get("updated_at")),
+    )
+
+
+def _graveyard_entry_from_dict(data: dict[str, Any]) -> GraveyardEntry:
+    return GraveyardEntry(
+        id=data["id"],
+        namespace_id=data["namespace_id"],
+        original_memory_id=data.get("original_memory_id"),
+        content=data["content"],
+        content_hash=data["content_hash"],
+        reason=GraveyardReason(data["reason"]),
+        buried_at=_parse_datetime(data["buried_at"]) or datetime.now(),
+        replaced_by_id=data.get("replaced_by_id"),
+        contradiction_id=data.get("contradiction_id"),
+        title=data.get("title"),
+        type=MemoryType(data.get("type", MemoryType.FACT.value)),
+        scope=MemoryScope(data.get("scope", MemoryScope.PROJECT.value)),
+        category=data.get("category"),
+        source=data.get("source"),
+        tags=list(data.get("tags", [])),
+        metadata=dict(data.get("metadata", {})),
+        confidence=float(data.get("confidence", 1.0)),
+        previous_tier=(
+            MemoryTier(data["previous_tier"])
+            if data.get("previous_tier") is not None
+            else None
+        ),
+        previous_status=(
+            MemoryStatus(data["previous_status"])
+            if data.get("previous_status") is not None
+            else None
+        ),
+        related_memory_ids=list(data.get("related_memory_ids", [])),
+        document_refs=list(data.get("document_refs", [])),
+        invalid_document_refs=list(data.get("invalid_document_refs", [])),
+        restore_hint=data.get("restore_hint"),
+        snapshot=dict(data.get("snapshot", {})),
+    )
+
+
+def _contradiction_from_dict(data: dict[str, Any]) -> Contradiction:
+    return Contradiction(
+        id=data["id"],
+        namespace_id=data["namespace_id"],
+        memory_a_id=data["memory_a_id"],
+        memory_b_id=data["memory_b_id"],
+        similarity=float(data["similarity"]),
+        status=ContradictionStatus(data["status"]),
+        created_at=_parse_datetime(data["created_at"]) or datetime.now(),
+        memory_a_summary=data.get("memory_a_summary"),
+        memory_b_summary=data.get("memory_b_summary"),
+        contradiction_kind=data.get("contradiction_kind"),
+        detected_by=data.get("detected_by"),
+        resolution=(
+            ContradictionResolution(data["resolution"])
+            if data.get("resolution") is not None
+            else None
+        ),
+        winner_memory_id=data.get("winner_memory_id"),
+        loser_memory_id=data.get("loser_memory_id"),
+        rationale=data.get("rationale"),
+        resolved_by=data.get("resolved_by"),
+        resolved_at=_parse_datetime(data.get("resolved_at")),
+        metadata=dict(data.get("metadata", {})),
+    )

snipara_memory/api/__init__.py

@@ -0,0 +1,5 @@
+"""API exports for snipara-memory."""
+
+from .fastapi_app import create_app
+
+__all__ = ["create_app"]

snipara_memory/api/fastapi_app.py

@@ -0,0 +1,95 @@
+"""Minimal FastAPI entrypoint for the standalone memory engine."""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from datetime import date, datetime
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
+
+from ..domain import (
+    MemoryScope,
+    MemoryService,
+    MemoryStatus,
+    MemoryTier,
+    MemoryType,
+    RecallQuery,
+    StoreMemoryRequest,
+)
+
+
+class StoreMemoryBody(BaseModel):
+    content: str = Field(..., min_length=1)
+    title: str | None = None
+    memory_type: MemoryType = MemoryType.FACT
+    scope: MemoryScope = MemoryScope.PROJECT
+    category: str | None = None
+    source: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    confidence: float = Field(default=0.7, ge=0.0, le=1.0)
+    relevance_boost: float = Field(default=1.0, ge=0.0)
+    tier: MemoryTier | None = None
+    status: MemoryStatus = MemoryStatus.ACTIVE
+    related_memory_ids: list[str] = Field(default_factory=list)
+    document_refs: list[str] = Field(default_factory=list)
+    invalid_document_refs: list[str] = Field(default_factory=list)
+    expires_at: datetime | None = None
+    journal_date: date | None = None
+
+
+class RecallBody(BaseModel):
+    query: str = Field(..., min_length=1)
+    limit: int = Field(default=10, ge=1, le=100)
+    min_confidence: float = Field(default=0.0, ge=0.0, le=1.0)
+    include_archived: bool = False
+    types: list[MemoryType] = Field(default_factory=list)
+    tiers: list[MemoryTier] = Field(default_factory=list)
+    tags: list[str] = Field(default_factory=list)
+
+
+def create_app(service: MemoryService) -> FastAPI:
+    """Create a standalone API app around the memory service."""
+    app = FastAPI(title="snipara-memory", version="0.1.0")
+
+    @app.get("/health")
+    async def health() -> dict[str, str]:
+        return {"status": "ok"}
+
+    @app.post("/v1/namespaces/{namespace_id}/memories")
+    async def store_memory(namespace_id: str, body: StoreMemoryBody) -> dict[str, Any]:
+        memory = await service.store_memory(
+            StoreMemoryRequest(namespace_id=namespace_id, **body.model_dump())
+        )
+        return asdict(memory)
+
+    @app.post("/v1/namespaces/{namespace_id}/memories/recall")
+    async def recall(namespace_id: str, body: RecallBody) -> list[dict[str, Any]]:
+        matches = await service.semantic_recall(
+            RecallQuery(namespace_id=namespace_id, **body.model_dump())
+        )
+        return [asdict(match) for match in matches]
+
+    @app.get("/v1/namespaces/{namespace_id}/session-memories")
+    async def session_memories(
+        namespace_id: str,
+        critical_limit: int = 12,
+        daily_limit: int = 20,
+        archive_limit: int = 20,
+    ) -> dict[str, Any]:
+        bundle = await service.get_session_memories(
+            namespace_id,
+            critical_limit=critical_limit,
+            daily_limit=daily_limit,
+            archive_limit=archive_limit,
+        )
+        return asdict(bundle)
+
+    @app.exception_handler(ValueError)
+    async def handle_value_error(_: Request, exc: ValueError) -> JSONResponse:
+        return JSONResponse(status_code=400, content={"detail": str(exc)})
+
+    return app