memex-python 0.13.0__py3-none-any.whl

memex/__init__.py

@@ -0,0 +1,336 @@
+"""memex — a typed, immutable, provenance-tracked memory graph for AI agents.
+
+Pydantic port of ``@ai2070/memex``. Public surface grows phase by phase; this
+barrel re-exports everything implemented so far.
+"""
+
+from __future__ import annotations
+
+from ._uuid import safe_extract_timestamp, uuid7
+from .bulk import (
+    ItemTransform,
+    ScoreAdjustment,
+    apply_many,
+    bulk_adjust_scores,
+    decay_importance,
+)
+from .commands import (
+    EdgeCreate,
+    EdgeRetract,
+    EdgeUpdate,
+    MemoryCommand,
+    MemoryCommandAdapter,
+    MemoryCreate,
+    MemoryRetract,
+    MemoryUpdate,
+)
+from .envelope import wrap_edge_state_event, wrap_lifecycle_event, wrap_state_event
+from .errors import (
+    DuplicateEdgeError,
+    DuplicateMemoryError,
+    EdgeNotFoundError,
+    InvalidTimestampError,
+    MemexError,
+    MemoryNotFoundError,
+)
+from .factories import create_edge, create_event_envelope, create_memory_item
+from .graph import GraphState, clone_graph_state, create_graph_state
+from .integrity import (
+    CascadeResult,
+    Contradiction,
+    StaleItem,
+    cascade_retract,
+    get_alias_group,
+    get_aliases,
+    get_contradictions,
+    get_dependents,
+    get_items_by_budget,
+    get_stale_items,
+    mark_alias,
+    mark_contradiction,
+    resolve_contradiction,
+)
+from .intent import (
+    DuplicateIntentError,
+    Intent,
+    IntentCommand,
+    IntentFilter,
+    IntentLifecycleEvent,
+    IntentNotFoundError,
+    IntentResult,
+    IntentState,
+    IntentStatus,
+    InvalidIntentTransitionError,
+    apply_intent_command,
+    create_intent,
+    create_intent_state,
+    get_child_intents,
+    get_intent_by_id,
+    get_intents,
+)
+from .models import (
+    CreatedFilter,
+    DecayConfig,
+    DecayFilter,
+    DecayInterval,
+    DecayType,
+    Edge,
+    EdgeFilter,
+    EventEnvelope,
+    KnownEdgeKind,
+    KnownMemoryKind,
+    KnownNamespace,
+    KnownSourceKind,
+    LifecycleEventType,
+    MemoryFilter,
+    MemoryItem,
+    MemoryLifecycleEvent,
+    ParentsFilter,
+    QueryOptions,
+    Range,
+    ScoredItem,
+    ScoreRanges,
+    ScoreWeights,
+    SortField,
+    SortOption,
+)
+from .query import (
+    ScoredQueryOptions,
+    compute_decay_multiplier,
+    compute_score,
+    extract_timestamp,
+    get_children,
+    get_edge_by_id,
+    get_edges,
+    get_item_by_id,
+    get_items,
+    get_parents,
+    get_related_items,
+    get_scored_items,
+    matches_filter,
+)
+from .reducer import CommandResult, apply_command, merge_edge, merge_item
+from .replay import (
+    ReplayFailure,
+    ReplayResult,
+    replay_commands,
+    replay_from_envelopes,
+)
+from .retrieval import (
+    DiversityOptions,
+    SupportNode,
+    apply_diversity,
+    filter_contradictions,
+    get_support_set,
+    get_support_tree,
+    smart_retrieve,
+    surface_contradictions,
+)
+from .serialization import (
+    SerializedGraphState,
+    from_json,
+    parse,
+    stringify,
+    to_json,
+)
+from .stats import EdgeStats, GraphStats, ItemStats, get_stats
+from .store import MemexStore
+from .task import (
+    DuplicateTaskError,
+    InvalidTaskTransitionError,
+    Task,
+    TaskCommand,
+    TaskFilter,
+    TaskLifecycleEvent,
+    TaskNotFoundError,
+    TaskResult,
+    TaskState,
+    TaskStatus,
+    apply_task_command,
+    create_task,
+    create_task_state,
+    get_child_tasks,
+    get_task_by_id,
+    get_tasks,
+    get_tasks_by_intent,
+)
+from .transplant import (
+    ExportOptions,
+    ImportBucket,
+    ImportOptions,
+    ImportReport,
+    ImportResult,
+    MemexExport,
+    export_slice,
+    import_slice,
+)
+
+__all__ = [
+    # uuid
+    "uuid7",
+    "safe_extract_timestamp",
+    # graph state
+    "GraphState",
+    "create_graph_state",
+    "clone_graph_state",
+    # reducer
+    "apply_command",
+    "CommandResult",
+    "merge_item",
+    "merge_edge",
+    # query
+    "get_items",
+    "get_scored_items",
+    "get_edges",
+    "get_item_by_id",
+    "get_edge_by_id",
+    "get_related_items",
+    "get_parents",
+    "get_children",
+    "matches_filter",
+    "compute_score",
+    "compute_decay_multiplier",
+    "extract_timestamp",
+    "ScoredQueryOptions",
+    # retrieval
+    "get_support_tree",
+    "get_support_set",
+    "filter_contradictions",
+    "surface_contradictions",
+    "apply_diversity",
+    "smart_retrieve",
+    "SupportNode",
+    "DiversityOptions",
+    # integrity
+    "get_contradictions",
+    "mark_contradiction",
+    "resolve_contradiction",
+    "get_stale_items",
+    "get_dependents",
+    "cascade_retract",
+    "mark_alias",
+    "get_aliases",
+    "get_alias_group",
+    "get_items_by_budget",
+    "Contradiction",
+    "StaleItem",
+    "CascadeResult",
+    # bulk
+    "apply_many",
+    "bulk_adjust_scores",
+    "decay_importance",
+    "ScoreAdjustment",
+    "ItemTransform",
+    # replay
+    "replay_commands",
+    "replay_from_envelopes",
+    "ReplayFailure",
+    "ReplayResult",
+    # envelope
+    "wrap_lifecycle_event",
+    "wrap_state_event",
+    "wrap_edge_state_event",
+    # serialization
+    "to_json",
+    "from_json",
+    "stringify",
+    "parse",
+    "SerializedGraphState",
+    # stats
+    "get_stats",
+    "GraphStats",
+    "ItemStats",
+    "EdgeStats",
+    # intent graph
+    "create_intent_state",
+    "create_intent",
+    "apply_intent_command",
+    "get_intents",
+    "get_intent_by_id",
+    "get_child_intents",
+    "Intent",
+    "IntentState",
+    "IntentStatus",
+    "IntentCommand",
+    "IntentFilter",
+    "IntentLifecycleEvent",
+    "IntentResult",
+    "IntentNotFoundError",
+    "DuplicateIntentError",
+    "InvalidIntentTransitionError",
+    # task graph
+    "create_task_state",
+    "create_task",
+    "apply_task_command",
+    "get_tasks",
+    "get_task_by_id",
+    "get_tasks_by_intent",
+    "get_child_tasks",
+    "Task",
+    "TaskState",
+    "TaskStatus",
+    "TaskCommand",
+    "TaskFilter",
+    "TaskLifecycleEvent",
+    "TaskResult",
+    "TaskNotFoundError",
+    "DuplicateTaskError",
+    "InvalidTaskTransitionError",
+    # transplant
+    "export_slice",
+    "import_slice",
+    "MemexExport",
+    "ExportOptions",
+    "ImportOptions",
+    "ImportReport",
+    "ImportBucket",
+    "ImportResult",
+    # facade
+    "MemexStore",
+    # factories
+    "create_memory_item",
+    "create_edge",
+    "create_event_envelope",
+    # models
+    "MemoryItem",
+    "Edge",
+    "EventEnvelope",
+    "DecayConfig",
+    "ScoreWeights",
+    "ScoredItem",
+    "MemoryFilter",
+    "EdgeFilter",
+    "SortOption",
+    "QueryOptions",
+    "Range",
+    "ScoreRanges",
+    "ParentsFilter",
+    "DecayFilter",
+    "CreatedFilter",
+    "MemoryLifecycleEvent",
+    # type aliases
+    "KnownMemoryKind",
+    "KnownSourceKind",
+    "KnownEdgeKind",
+    "KnownNamespace",
+    "LifecycleEventType",
+    "SortField",
+    "DecayInterval",
+    "DecayType",
+    # commands
+    "MemoryCommand",
+    "MemoryCommandAdapter",
+    "MemoryCreate",
+    "MemoryUpdate",
+    "MemoryRetract",
+    "EdgeCreate",
+    "EdgeUpdate",
+    "EdgeRetract",
+    # errors
+    "MemexError",
+    "MemoryNotFoundError",
+    "EdgeNotFoundError",
+    "DuplicateMemoryError",
+    "DuplicateEdgeError",
+    "InvalidTimestampError",
+]

memex/_time.py

@@ -0,0 +1,26 @@
+"""Internal clock helpers.
+
+Isolated in one module so tests can monkeypatch ``now_ms`` / ``now_iso``
+deterministically (the analog of stubbing ``Date.now`` / ``Date.toISOString``).
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime, timezone
+
+
+def now_ms() -> int:
+    """Current unix time in milliseconds (mirrors JS ``Date.now()``)."""
+    return int(time.time() * 1000)
+
+
+def now_iso() -> str:
+    """Current UTC time as ISO-8601 with millisecond precision and a ``Z`` suffix.
+
+    Matches JavaScript ``new Date().toISOString()`` byte-for-byte
+    (e.g. ``"2024-06-22T13:45:30.123Z"``), which the strict replay parser
+    in :mod:`memex.replay` accepts.
+    """
+    dt = datetime.now(timezone.utc)
+    return dt.strftime("%Y-%m-%dT%H:%M:%S.") + f"{dt.microsecond // 1000:03d}Z"

memex/_uuid.py

@@ -0,0 +1,62 @@
+"""UUIDv7 generation and timestamp extraction.
+
+Mirrors the single runtime dependency of the TypeScript library (``uuidv7``)
+with a tiny internal implementation so the only third-party dependency is
+``pydantic``. UUIDv7 (RFC 9562) encodes a 48-bit big-endian millisecond
+timestamp in its first six bytes; we decode exactly those bytes the same way
+the TS ``safeExtractTimestamp`` does.
+"""
+
+from __future__ import annotations
+
+import os
+from uuid import UUID
+
+from . import _time
+
+__all__ = ["uuid7", "safe_extract_timestamp"]
+
+
+def uuid7(ms: int | None = None) -> str:
+    """Generate a UUIDv7 string for ``ms`` (defaults to the current time)."""
+    if ms is None:
+        ms = _time.now_ms()
+    ts = ms & ((1 << 48) - 1)
+    rand = os.urandom(10)
+
+    b = bytearray(16)
+    b[0] = (ts >> 40) & 0xFF
+    b[1] = (ts >> 32) & 0xFF
+    b[2] = (ts >> 24) & 0xFF
+    b[3] = (ts >> 16) & 0xFF
+    b[4] = (ts >> 8) & 0xFF
+    b[5] = ts & 0xFF
+    b[6] = 0x70 | (rand[0] & 0x0F)  # version 7 in the high nibble
+    b[7] = rand[1]
+    b[8] = 0x80 | (rand[2] & 0x3F)  # RFC 4122 variant (0b10) in the top bits
+    b[9:16] = rand[3:10]
+    return str(UUID(bytes=bytes(b)))
+
+
+def safe_extract_timestamp(value: str) -> int | None:
+    """Decode the millisecond timestamp from a UUIDv7 id.
+
+    Returns ``None`` for anything that is not a valid version-7 UUID, or whose
+    encoded timestamp is non-positive — matching the TS helper's tolerance.
+    """
+    try:
+        parsed = UUID(value)
+    except (ValueError, AttributeError, TypeError):
+        return None
+    if parsed.version != 7:
+        return None
+    b = parsed.bytes
+    ts = (
+        (b[0] << 40)
+        | (b[1] << 32)
+        | (b[2] << 24)
+        | (b[3] << 16)
+        | (b[4] << 8)
+        | b[5]
+    )
+    return ts if ts > 0 else None

memex/bulk.py

@@ -0,0 +1,138 @@
+"""Bulk operations: single-pass transforms, score adjustments, importance decay."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from pydantic import BaseModel
+
+from . import _time
+from .graph import GraphState
+from .models import Edge, MemoryFilter, MemoryItem, MemoryLifecycleEvent, QueryOptions
+from .query import get_items
+from .reducer import CommandResult, merge_item
+
+__all__ = ["ScoreAdjustment", "ItemTransform", "apply_many", "bulk_adjust_scores", "decay_importance"]
+
+ItemTransform = Callable[[MemoryItem], "dict[str, Any] | None"]
+
+
+class ScoreAdjustment(BaseModel):
+    authority: float | None = None
+    conviction: float | None = None
+    importance: float | None = None
+
+
+def _clamp(value: float) -> float:
+    return max(0.0, min(1.0, value))
+
+
+def apply_many(
+    state: GraphState,
+    filter: MemoryFilter | dict[str, Any] | None,
+    transform: ItemTransform,
+    author: str,
+    reason: str | None = None,
+    options: QueryOptions | dict[str, Any] | None = None,
+) -> CommandResult:
+    """Apply ``transform`` to every matching item in a single pass.
+
+    ``transform`` returns ``None`` to retract (also cleaning up incident edges),
+    an empty dict to skip, or a partial to update. The items dict is cloned once;
+    the edges dict and a reverse index are built lazily on the first retract.
+    """
+    matched = get_items(state, filter, options)
+    if not matched:
+        return CommandResult(state, [])
+
+    items = dict(state.items)
+    edges: dict[str, Edge] | None = None
+    edges_by_endpoint: dict[str, list[str]] | None = None
+    all_events: list[MemoryLifecycleEvent] = []
+    changed = False
+
+    for item in matched:
+        if item.id not in items:
+            continue
+
+        partial = transform(item)
+
+        if partial is None:
+            del items[item.id]
+            all_events.append(
+                MemoryLifecycleEvent(type="memory.retracted", item=item, cause_type="memory.retract")
+            )
+            changed = True
+            if state.edges:
+                if edges is None:
+                    edges = dict(state.edges)
+                if edges_by_endpoint is None:
+                    edges_by_endpoint = {}
+                    for edge_id, edge in state.edges.items():
+                        edges_by_endpoint.setdefault(edge.from_, []).append(edge_id)
+                        if edge.from_ != edge.to:
+                            edges_by_endpoint.setdefault(edge.to, []).append(edge_id)
+                incident_ids = edges_by_endpoint.get(item.id)
+                if incident_ids:
+                    for edge_id in incident_ids:
+                        incident_edge = edges.get(edge_id)
+                        if incident_edge is None:
+                            continue  # already cleaned by a prior retract
+                        del edges[edge_id]
+                        all_events.append(
+                            MemoryLifecycleEvent(type="edge.retracted", edge=incident_edge, cause_type="memory.retract")
+                        )
+        elif len(partial) > 0:
+            merged = merge_item(item, partial)
+            items[item.id] = merged
+            all_events.append(
+                MemoryLifecycleEvent(type="memory.updated", item=merged, cause_type="memory.update")
+            )
+            changed = True
+
+    if not changed:
+        return CommandResult(state, [])
+
+    return CommandResult(GraphState(items, edges if edges is not None else state.edges), all_events)
+
+
+def bulk_adjust_scores(
+    state: GraphState,
+    criteria: MemoryFilter | dict[str, Any],
+    delta: ScoreAdjustment | dict[str, Any],
+    author: str,
+    reason: str | None = None,
+) -> CommandResult:
+    d = delta if isinstance(delta, ScoreAdjustment) else ScoreAdjustment.model_validate(delta)
+
+    def transform(item: MemoryItem) -> dict[str, Any]:
+        partial: dict[str, Any] = {}
+        if d.authority is not None:
+            partial["authority"] = _clamp(item.authority + d.authority)
+        if d.conviction is not None:
+            partial["conviction"] = _clamp((item.conviction or 0) + d.conviction)
+        if d.importance is not None:
+            partial["importance"] = _clamp((item.importance or 0) + d.importance)
+        return partial
+
+    return apply_many(state, criteria, transform, author, reason)
+
+
+def decay_importance(
+    state: GraphState,
+    older_than_ms: int,
+    factor: float,
+    author: str,
+    reason: str | None = None,
+) -> CommandResult:
+    """Decay importance on items created before a cutoff time."""
+    cutoff = _time.now_ms() - older_than_ms
+
+    def transform(item: MemoryItem) -> dict[str, Any]:
+        current = item.importance if item.importance is not None else 0
+        if current == 0:
+            return {}
+        return {"importance": _clamp(current * factor)}
+
+    return apply_many(state, {"created": {"before": cutoff}}, transform, author, reason or "time-based importance decay")

memex/commands.py

@@ -0,0 +1,75 @@
+"""Memory commands as a Pydantic discriminated union.
+
+This single module replaces the entire ``schemas.ts`` / Zod layer: in Pydantic
+the command models *are* the schema. ``apply_command`` accepts either a command
+model instance or a plain dict (validated through ``MemoryCommandAdapter``),
+which keeps the TS object-literal call style portable.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field, TypeAdapter
+
+from .models import Edge, MemoryItem
+
+__all__ = [
+    "MemoryCreate",
+    "MemoryUpdate",
+    "MemoryRetract",
+    "EdgeCreate",
+    "EdgeUpdate",
+    "EdgeRetract",
+    "MemoryCommand",
+    "MemoryCommandAdapter",
+]
+
+
+class MemoryCreate(BaseModel):
+    type: Literal["memory.create"] = "memory.create"
+    item: MemoryItem
+
+
+class MemoryUpdate(BaseModel):
+    type: Literal["memory.update"] = "memory.update"
+    item_id: str
+    partial: dict[str, Any]
+    author: str
+    reason: str | None = None
+    basis: dict[str, Any] | None = None
+
+
+class MemoryRetract(BaseModel):
+    type: Literal["memory.retract"] = "memory.retract"
+    item_id: str
+    author: str
+    reason: str | None = None
+
+
+class EdgeCreate(BaseModel):
+    type: Literal["edge.create"] = "edge.create"
+    edge: Edge
+
+
+class EdgeUpdate(BaseModel):
+    type: Literal["edge.update"] = "edge.update"
+    edge_id: str
+    partial: dict[str, Any]
+    author: str
+    reason: str | None = None
+
+
+class EdgeRetract(BaseModel):
+    type: Literal["edge.retract"] = "edge.retract"
+    edge_id: str
+    author: str
+    reason: str | None = None
+
+
+MemoryCommand = Annotated[
+    MemoryCreate | MemoryUpdate | MemoryRetract | EdgeCreate | EdgeUpdate | EdgeRetract,
+    Field(discriminator="type"),
+]
+
+MemoryCommandAdapter: TypeAdapter[MemoryCommand] = TypeAdapter(MemoryCommand)

memex/envelope.py

@@ -0,0 +1,69 @@
+"""Helpers that wrap lifecycle events / state snapshots into event envelopes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import _time
+from ._uuid import uuid7
+from .models import Edge, EventEnvelope, MemoryItem, MemoryLifecycleEvent
+
+__all__ = ["wrap_lifecycle_event", "wrap_state_event", "wrap_edge_state_event"]
+
+
+def _event_fields(event: MemoryLifecycleEvent) -> dict[str, Any]:
+    # Mirror the TS object spread: only keys that are set (item/edge/cause_type
+    # may be absent). Nested item/edge are kept as models until serialized.
+    fields: dict[str, Any] = {"namespace": event.namespace, "type": event.type}
+    if event.item is not None:
+        fields["item"] = event.item
+    if event.edge is not None:
+        fields["edge"] = event.edge
+    if event.cause_type is not None:
+        fields["cause_type"] = event.cause_type
+    return fields
+
+
+def wrap_lifecycle_event(
+    event: MemoryLifecycleEvent,
+    cause_id: str,
+    trace_id: str | None = None,
+) -> EventEnvelope[dict[str, Any]]:
+    return EventEnvelope(
+        id=uuid7(),
+        namespace="memory",
+        type=event.type,
+        ts=_time.now_iso(),
+        trace_id=trace_id,
+        payload={**_event_fields(event), "cause_id": cause_id},
+    )
+
+
+def wrap_state_event(
+    item: MemoryItem,
+    cause_id: str,
+    trace_id: str | None = None,
+) -> EventEnvelope[dict[str, Any]]:
+    return EventEnvelope(
+        id=uuid7(),
+        namespace="memory",
+        type="state.memory",
+        ts=_time.now_iso(),
+        trace_id=trace_id,
+        payload={"item": item, "cause_id": cause_id},
+    )
+
+
+def wrap_edge_state_event(
+    edge: Edge,
+    cause_id: str,
+    trace_id: str | None = None,
+) -> EventEnvelope[dict[str, Any]]:
+    return EventEnvelope(
+        id=uuid7(),
+        namespace="memory",
+        type="state.edge",
+        ts=_time.now_iso(),
+        trace_id=trace_id,
+        payload={"edge": edge, "cause_id": cause_id},
+    )