spomory 0.1.0__py3-none-any.whl

memory_core/audit.py

@@ -0,0 +1,69 @@
+"""Append-only audit log for data-deletion events (Epic 10.3).
+
+Backs the "记忆主权" promise's verifiability: every true-delete (Epic 7.3)
+should leave behind a tamper-evident record of when it happened and what
+was removed, even though the underlying data itself is gone.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import uuid
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS audit_log (
+    id TEXT PRIMARY KEY,
+    event_type TEXT NOT NULL,
+    user_id TEXT NOT NULL,
+    detail TEXT NOT NULL,
+    created_at TEXT NOT NULL
+);
+"""
+
+
+@dataclass
+class AuditRecord:
+    id: str
+    event_type: str
+    user_id: str
+    detail: dict[str, object]
+    created_at: str
+
+
+class AuditLog:
+    """Append-only by convention: this class exposes no update/delete methods."""
+
+    def __init__(self, db_path: str | Path = ":memory:") -> None:
+        self._conn = sqlite3.connect(str(db_path), check_same_thread=False)
+        self._conn.executescript(_SCHEMA)
+        self._conn.commit()
+
+    def record_deletion(self, user_id: str, entities_deleted: int, relations_deleted: int) -> AuditRecord:
+        record = AuditRecord(
+            id=str(uuid.uuid4()),
+            event_type="true_delete",
+            user_id=user_id,
+            detail={"entities_deleted": entities_deleted, "relations_deleted": relations_deleted},
+            created_at=datetime.now(UTC).isoformat(),
+        )
+        self._conn.execute(
+            "INSERT INTO audit_log (id, event_type, user_id, detail, created_at) VALUES (?, ?, ?, ?, ?)",
+            (record.id, record.event_type, record.user_id, json.dumps(record.detail), record.created_at),
+        )
+        self._conn.commit()
+        return record
+
+    def query(self, user_id: str) -> list[AuditRecord]:
+        rows = self._conn.execute(
+            "SELECT id, event_type, user_id, detail, created_at FROM audit_log "
+            "WHERE user_id = ? ORDER BY created_at",
+            (user_id,),
+        ).fetchall()
+        return [
+            AuditRecord(id=r[0], event_type=r[1], user_id=r[2], detail=json.loads(r[3]), created_at=r[4])
+            for r in rows
+        ]

memory_core/export/exporter.py

@@ -0,0 +1,69 @@
+"""Full export and true-delete: the technical backing for the "记忆护照"
+promise — export the whole graph, or physically erase it, on demand.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from memory_core.audit import AuditLog
+from memory_core.graph.store import GraphStoreBase
+
+from .schema import ExportedEntity, ExportedRelation, MemoryExport
+
+
+def export_all(store: GraphStoreBase, subject_id: str) -> MemoryExport:
+    entities = [ExportedEntity.from_entity(e) for e in store.all_entities()]
+    relations = [ExportedRelation.from_relation(r) for r in store.all_relations()]
+    return MemoryExport(subject_id=subject_id, entities=entities, relations=relations)
+
+
+@dataclass
+class DeletionReceipt:
+    """A verifiable confirmation that data was physically removed, not just hidden."""
+
+    subject_id: str
+    entities_deleted: int
+    relations_deleted: int
+    entities_remaining: int
+    relations_remaining: int
+
+    @property
+    def fully_deleted(self) -> bool:
+        return self.entities_remaining == 0 and self.relations_remaining == 0
+
+
+def delete_all(
+    store: GraphStoreBase, subject_id: str, audit_log: AuditLog | None = None
+) -> DeletionReceipt:
+    """Physically delete every entity (and, transitively, every relation touching one).
+
+    If ``audit_log`` is given, the deletion is recorded there (Epic 10.3) —
+    a tamper-evident record that the deletion happened, kept separately
+    from the data that was actually removed.
+    """
+    entities_before = store.all_entities()
+    relations_before = len(store.all_relations())
+
+    for entity in entities_before:
+        store.delete_entity(entity.id)
+
+    remaining_entities = store.all_entities()
+    remaining_relations = store.all_relations()
+
+    receipt = DeletionReceipt(
+        subject_id=subject_id,
+        entities_deleted=len(entities_before) - len(remaining_entities),
+        relations_deleted=relations_before - len(remaining_relations),
+        entities_remaining=len(remaining_entities),
+        relations_remaining=len(remaining_relations),
+    )
+
+    if audit_log is not None:
+        audit_log.record_deletion(
+            user_id=subject_id,
+            entities_deleted=receipt.entities_deleted,
+            relations_deleted=receipt.relations_deleted,
+        )
+
+    return receipt

memory_core/export/schema.py

@@ -0,0 +1,90 @@
+"""The "记忆护照" (memory passport) export schema.
+
+Design follows the MIF/PAM early-draft conventions cited in the business
+plan: semantic/episodic/procedural memory classification, W3C PROV-O-style
+provenance (not the full spec, just its shape — source, derivation span,
+extractor), and a JSON-LD-flavored top-level ``@context``/``@type`` so the
+file is self-describing without inventing a private format from scratch.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from memory_core.graph.models import Entity, Relation
+
+JSONLD_CONTEXT: dict[str, Any] = {
+    "@vocab": "https://schema.org/",
+    "memory": "https://memory-core.dev/schema/memory#",
+    "prov": "http://www.w3.org/ns/prov#",
+}
+
+
+class ExportedEntity(BaseModel):
+    """An entity as it appears in an export file — same fields as ``Entity``,
+    kept as a distinct model so the export format can evolve independently
+    of the internal storage model."""
+
+    id: str
+    name: str
+    type: str
+    memory_type: str
+    attributes: dict[str, str]
+    aliases: list[str]
+    provenance: list[dict[str, str]]
+    created_at: datetime
+    updated_at: datetime
+
+    @classmethod
+    def from_entity(cls, entity: Entity) -> ExportedEntity:
+        return cls(
+            id=entity.id,
+            name=entity.name,
+            type=entity.type,
+            memory_type=entity.memory_type,
+            attributes=entity.attributes,
+            aliases=entity.aliases,
+            provenance=[p.model_dump() for p in entity.provenance],
+            created_at=entity.created_at,
+            updated_at=entity.updated_at,
+        )
+
+
+class ExportedRelation(BaseModel):
+    id: str
+    subject_id: str
+    predicate: str
+    object_id: str
+    confidence: float
+    memory_type: str
+    provenance: list[dict[str, str]]
+    created_at: datetime
+    updated_at: datetime
+
+    @classmethod
+    def from_relation(cls, relation: Relation) -> ExportedRelation:
+        return cls(
+            id=relation.id,
+            subject_id=relation.subject_id,
+            predicate=relation.predicate,
+            object_id=relation.object_id,
+            confidence=relation.confidence,
+            memory_type=relation.memory_type,
+            provenance=[p.model_dump() for p in relation.provenance],
+            created_at=relation.created_at,
+            updated_at=relation.updated_at,
+        )
+
+
+class MemoryExport(BaseModel):
+    context: dict[str, Any] = Field(default=JSONLD_CONTEXT, alias="@context")
+    type: str = Field(default="memory:MemoryPassport", alias="@type")
+    exported_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    subject_id: str
+    entities: list[ExportedEntity]
+    relations: list[ExportedRelation]
+
+    model_config = {"populate_by_name": True}

memory_core/graph/extract.py

@@ -0,0 +1,16 @@
+"""Text -> candidate triples extraction pipeline.
+
+Thin wrapper over ``LLMProvider.extract_triples`` today; kept as its own
+module because Epic 1.5's incremental merge logic needs a stable seam to
+call into (and to swap in more elaborate chunking/prompting later without
+touching callers).
+"""
+
+from __future__ import annotations
+
+from memory_core.llm.base import LLMProvider, TripleCandidate
+
+
+def extract_candidate_triples(text: str, llm: LLMProvider) -> list[TripleCandidate]:
+    """Extract candidate (subject, predicate, object) triples with source spans."""
+    return llm.extract_triples(text)

memory_core/graph/incremental.py

@@ -0,0 +1,174 @@
+"""Incremental write/merge logic.
+
+Only the newly-extracted triples are touched on each call — there is no
+step here that re-reads or re-derives the rest of the graph, which is the
+property that makes this "incremental" rather than an indexer that
+rebuilds everything (the LightRAG-style design choice called out in the
+business plan, as opposed to GraphRAG's full-rebuild-per-update approach).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from memory_core.llm.base import LLMProvider
+from memory_core.llm.redact import redact_secrets
+
+from .models import Entity, Provenance, Relation
+from .store import GraphStoreBase
+
+if TYPE_CHECKING:
+    from memory_core.memory_manager.policy import MemoryPolicy
+
+
+# Epic 12.4: exact-match, case/punctuation-insensitive filler phrases that
+# carry no extractable fact -- deliberately a small, conservative allowlist
+# rather than a length threshold or fuzzy match, so a short but meaningful
+# sentence ("I quit.") is never mistaken for filler. Skipping these avoids
+# an LLM extraction call (real money, and the only thing standing between a
+# public endpoint like /demo/try and a free way to burn API budget) for
+# input that could never contain a triple anyway.
+_LOW_INFORMATION_PHRASES = {
+    "thanks",
+    "thank you",
+    "ok",
+    "okay",
+    "got it",
+    "sounds good",
+    "sure",
+    "yes",
+    "no",
+    "hi",
+    "hello",
+    "bye",
+    "goodbye",
+    "谢谢",
+    "谢谢你",
+    "好的",
+    "好",
+    "嗯",
+    "在吗",
+    "在",
+    "明白",
+    "明白了",
+    "知道了",
+    "收到",
+}
+
+_STRIP_CHARS = " \t\n\r!?。！？.,，、~～"
+
+
+def _is_low_information(text: str) -> bool:
+    normalized = text.strip(_STRIP_CHARS).lower()
+    return normalized in _LOW_INFORMATION_PHRASES
+
+
+@dataclass
+class IngestResult:
+    new_entities: int = 0
+    merged_entities: int = 0
+    new_relations: int = 0
+    updated_relations: int = 0
+    noop_relations: int = 0
+    entity_ids_by_name: dict[str, str] = field(default_factory=dict)
+
+
+class IncrementalIngestor:
+    """Extracts triples from new text and merges them into an existing ``GraphStoreBase``.
+
+    Entity resolution policy: an incoming subject/object name is merged into
+    an existing entity only on an exact (case/whitespace-insensitive) match
+    against that entity's name or a known alias. Ambiguous cases (multiple
+    existing entities share the name) are resolved conservatively by
+    creating a new entity rather than risking a false merge between two
+    distinct same-named entities — a false split is easier to fix later
+    than a false merge that silently conflates two people/things.
+    """
+
+    def __init__(
+        self, store: GraphStoreBase, llm: LLMProvider, policy: MemoryPolicy | None = None
+    ) -> None:
+        """``policy`` (Epic 3.2/3.5): when given, every extracted candidate is
+        routed through ``policy.decide()`` (ADD/UPDATE/DELETE/NOOP) instead of
+        being unconditionally written — this is what actually wires Epic 3's
+        memory-management layer into the ingestion path Epic 1+2 use, rather
+        than leaving it a standalone, never-called module. Defaults to
+        ``None`` (unconditional add/merge) to keep existing callers'
+        behavior unchanged.
+        """
+        self.store = store
+        self.llm = llm
+        self.policy = policy
+
+    def ingest(self, text: str, source_id: str) -> IngestResult:
+        result = IngestResult()
+        if _is_low_information(text):
+            return result
+
+        text = redact_secrets(text)
+        candidates = self.llm.extract_triples(text)
+
+        new_entities: list[Entity] = []
+        pending_relations: list[Relation] = []
+
+        def resolve(name: str) -> str:
+            if name in result.entity_ids_by_name:
+                return result.entity_ids_by_name[name]
+
+            matches = self.store.find_entities_by_name(name)
+            if len(matches) == 1:
+                entity = matches[0]
+                result.merged_entities += 1
+            else:
+                entity = Entity(name=name, type="unknown")
+                new_entities.append(entity)
+                result.new_entities += 1
+
+            result.entity_ids_by_name[name] = entity.id
+            return entity.id
+
+        for candidate in candidates:
+            subject_id = resolve(candidate.subject)
+            object_id = resolve(candidate.object)
+            relation = Relation(
+                subject_id=subject_id,
+                predicate=candidate.predicate,
+                object_id=object_id,
+                provenance=[Provenance(source_id=source_id, source_span=candidate.source_span)],
+            )
+
+            if self.policy is None:
+                pending_relations.append(relation)
+                result.new_relations += 1
+                continue
+
+            # New entities must be visible to the store before the policy can
+            # meaningfully query "what do we already know about this subject"
+            # (get_neighbors), so flush them immediately rather than batching.
+            if new_entities:
+                self.store.add_entities(new_entities)
+                new_entities = []
+            self._apply_via_policy(relation, result)
+
+        if new_entities:
+            self.store.add_entities(new_entities)
+        if pending_relations:
+            self.store.add_relations(pending_relations)
+
+        return result
+
+    def _apply_via_policy(self, relation: Relation, result: IngestResult) -> None:
+        from memory_core.memory_manager.actions import ActionType, apply_action
+
+        action = self.policy.decide(relation, self.store)
+        apply_action(action, self.store)
+
+        if action.action_type is ActionType.ADD:
+            result.new_relations += 1
+        elif action.action_type is ActionType.UPDATE:
+            result.updated_relations += 1
+        elif action.action_type is ActionType.NOOP:
+            result.noop_relations += 1
+        # DELETE isn't reachable from RuleBasedPolicy's own candidate-vs-existing
+        # comparison today, but is handled uniformly by apply_action() either way.