typedmem 0.4.0__py3-none-any.whl

typedmem/__init__.py

@@ -0,0 +1,77 @@
+"""TypedMemory: structured, policy-aware memory for AI systems."""
+
+from .embeddings import EmbeddingProvider, HashingEmbeddingProvider, cosine
+from .evolvers import (
+    ContradictionSurfacer,
+    EvolutionRecord,
+    EvolutionResult,
+    Evolver,
+    GoalResolver,
+    PreferenceDriftDetector,
+    SummaryEvolver,
+    revert_goal_resolution,
+)
+from .extractor import ExtractionResult, Extractor, LLMExtractor, RuleBasedExtractor
+from .llm import AnthropicClient, FakeClient, LLMClient, OpenAIClient
+from .policy import (
+    DEFAULT_POLICIES,
+    ConflictAction,
+    ConflictPolicy,
+    PolicyEngine,
+    TypePolicy,
+)
+from .profiles import DomainProfile, TypeSpec
+from .prompts import PROMPTS
+from .retriever import RelevanceWeights, Retriever, ScoredMemory
+from .schema import GoalStatus, Memory, MemoryType
+from .source import Source
+from .stores import (
+    InMemoryStore,
+    JSONLMemoryStore,
+    MemoryStore,
+    SQLiteMemoryStore,
+)
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "DEFAULT_POLICIES",
+    "AnthropicClient",
+    "ConflictAction",
+    "ConflictPolicy",
+    "ContradictionSurfacer",
+    "DomainProfile",
+    "EmbeddingProvider",
+    "EvolutionRecord",
+    "EvolutionResult",
+    "Evolver",
+    "ExtractionResult",
+    "Extractor",
+    "FakeClient",
+    "GoalResolver",
+    "GoalStatus",
+    "HashingEmbeddingProvider",
+    "InMemoryStore",
+    "JSONLMemoryStore",
+    "LLMClient",
+    "LLMExtractor",
+    "Memory",
+    "MemoryStore",
+    "MemoryType",
+    "OpenAIClient",
+    "PROMPTS",
+    "PolicyEngine",
+    "PreferenceDriftDetector",
+    "RelevanceWeights",
+    "Retriever",
+    "RuleBasedExtractor",
+    "ScoredMemory",
+    "SQLiteMemoryStore",
+    "Source",
+    "SummaryEvolver",
+    "TypePolicy",
+    "TypeSpec",
+    "__version__",
+    "cosine",
+    "revert_goal_resolution",
+]

typedmem/cli.py

@@ -0,0 +1,316 @@
+"""``typedmem`` CLI.
+
+Default store: SQLite at $TYPEDMEM_DB or ``~/.typedmem/memories.db``.
+Override per invocation with ``--store path.db`` or ``--store path.jsonl``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from . import (
+    ContradictionSurfacer,
+    DomainProfile,
+    GoalResolver,
+    HashingEmbeddingProvider,
+    JSONLMemoryStore,
+    LLMExtractor,  # noqa: F401  (kept for docs / future use)
+    Memory,
+    MemoryStore,
+    MemoryType,
+    PolicyEngine,
+    PreferenceDriftDetector,
+    Retriever,
+    RuleBasedExtractor,
+    SQLiteMemoryStore,
+    Source,
+)
+from .profiles import BUILTIN_PROFILES, from_json as _profile_from_json, from_yaml as _profile_from_yaml
+
+
+def _default_store_path() -> Path:
+    env = os.environ.get("TYPEDMEM_DB")
+    if env:
+        return Path(env)
+    return Path.home() / ".typedmem" / "memories.db"
+
+
+def _load_profile(name: str | None, path: str | None) -> DomainProfile | None:
+    if path:
+        p = Path(path)
+        if p.suffix in {".yaml", ".yml"}:
+            return _profile_from_yaml(p)
+        return _profile_from_json(p)
+    if name:
+        return DomainProfile.builtin(name)
+    return None
+
+
+def _open_store(path: Path, workspace: str, profile: DomainProfile | None) -> MemoryStore:
+    policy = PolicyEngine.from_profile(profile) if profile else None
+    if path.suffix in {".jsonl", ".ndjson"}:
+        return JSONLMemoryStore(path, policy=policy, default_workspace=workspace, profile=profile)
+    return SQLiteMemoryStore(path, policy=policy, default_workspace=workspace, profile=profile)
+
+
+def _fmt(m: Memory) -> str:
+    subj = f" [{m.subject}]" if m.subject else ""
+    tags = f" #{','.join(m.tags)}" if m.tags else ""
+    ws = "" if m.workspace == "default" else f" @{m.workspace}"
+    return f"{m.timestamp.date()} {m.type:<11}{subj}{ws} conf={m.confidence:.2f}{tags}  {m.content}"
+
+
+def _source_from_args(args: argparse.Namespace) -> Source | None:
+    if not getattr(args, "document_id", None):
+        return None
+    kwargs = {"document_id": args.document_id}
+    if getattr(args, "uri", None):
+        kwargs["uri"] = args.uri
+    if getattr(args, "authority", None) is not None:
+        kwargs["authority"] = args.authority
+    return Source(**kwargs)
+
+
+def cmd_add(args: argparse.Namespace, store: MemoryStore) -> int:
+    source = _source_from_args(args)
+    if args.type:
+        m = Memory(
+            type=args.type,                          # any string; profile validates if bound
+            content=args.text,
+            subject=args.subject,
+            tags=args.tags or [],
+            confidence=args.confidence,
+            workspace=args.workspace,
+            sources=[source] if source else [],
+        )
+        store.add(m)
+        print(f"added 1 memory ({m.type}): {m.id}")
+        return 0
+    extractor = RuleBasedExtractor()
+    extracted = extractor.extract(
+        args.text, subject=args.subject, workspace=args.workspace, default_source=source,
+    )
+    if not extracted:
+        print("no memories extracted; pass --type to force a single typed memory", file=sys.stderr)
+        return 1
+    for m in extracted:
+        store.add(m)
+    print(f"added {len(extracted)} memorie(s) from extractor")
+    for m in extracted:
+        print("  " + _fmt(m))
+    return 0
+
+
+def cmd_search(args: argparse.Namespace, store: MemoryStore) -> int:
+    embedder = None if args.no_embed else HashingEmbeddingProvider(dim=args.dim)
+    retriever = Retriever(store, embedder=embedder)
+    types = list(args.type) if args.type else None
+    tags = args.tag or None
+    hits = retriever.relevant(
+        args.query, limit=args.limit, types=types, tags=tags,
+        workspace=args.workspace, include_superseded=args.include_superseded,
+    )
+    if not hits:
+        print("no matches")
+        return 0
+    for h in hits:
+        print(f"{h.score:.3f}  " + _fmt(h.memory))
+    return 0
+
+
+def cmd_list(args: argparse.Namespace, store: MemoryStore) -> int:
+    if args.type:
+        items = store.by_type(
+            args.type, workspace=args.workspace,
+            include_superseded=args.include_superseded,
+        )
+    else:
+        items = store.all(
+            workspace=args.workspace, include_superseded=args.include_superseded,
+        )
+    items.sort(key=lambda m: m.timestamp, reverse=True)
+    if args.limit:
+        items = items[: args.limit]
+    if args.json:
+        print(json.dumps([m.to_dict() for m in items], indent=2))
+        return 0
+    if not items:
+        print("no memories")
+        return 0
+    for m in items:
+        print(_fmt(m))
+    return 0
+
+
+def cmd_delete(args: argparse.Namespace, store: MemoryStore) -> int:
+    ok = store.delete(args.id)
+    print("deleted" if ok else "not found")
+    return 0 if ok else 1
+
+
+def cmd_compact(args: argparse.Namespace, store: MemoryStore) -> int:
+    if isinstance(store, JSONLMemoryStore):
+        store.compact()
+        print("compacted")
+        return 0
+    print("compact is only supported for JSONL stores", file=sys.stderr)
+    return 1
+
+
+def cmd_workspaces(args: argparse.Namespace, store: MemoryStore) -> int:
+    names = store.workspaces()
+    if not names:
+        print("(no workspaces yet)")
+        return 0
+    for name in names:
+        print(name)
+    return 0
+
+
+def _format_record(r) -> str:
+    return f"  [{r.action}] {r.reason}  (in={r.input_ids}, out={r.output_ids})"
+
+
+def cmd_evolve(args: argparse.Namespace, store: MemoryStore) -> int:
+    evolver_kind = args.evolver
+    if evolver_kind == "contradictions":
+        evolver = ContradictionSurfacer()
+        dry_run = False  # read-only; flag is informational
+    elif evolver_kind == "drift":
+        evolver = PreferenceDriftDetector(
+            min_replaces=args.min_replaces, window_days=args.window_days,
+        )
+        # Drift annotation is reversible (just a metadata key) — default to commit.
+        dry_run = not args.apply
+    elif evolver_kind == "goals":
+        evolver = GoalResolver(
+            HashingEmbeddingProvider(dim=args.dim),
+            threshold=args.threshold,
+        )
+        # Destructive: default to dry-run, require --apply to commit.
+        dry_run = not args.apply
+    else:
+        print(f"unknown evolver: {evolver_kind}", file=sys.stderr)
+        return 1
+
+    result = evolver.evolve(store, workspace=args.workspace, dry_run=dry_run)
+    print(result.summary())
+    for r in result.records:
+        print(_format_record(r))
+    return 0
+
+
+def cmd_history(args: argparse.Namespace, store: MemoryStore) -> int:
+    entries = store.evolution_history(args.id)
+    if not entries:
+        print("(no evolution history)")
+        return 0
+    for e in entries:
+        ts = e.get("timestamp", "?")
+        print(f"{ts}  [{e.get('evolver','?')}] {e.get('action','?')}: {e.get('reason','')}")
+    return 0
+
+
+def cmd_profiles(args: argparse.Namespace, store: MemoryStore) -> int:
+    for name, factory in sorted(BUILTIN_PROFILES.items()):
+        profile = factory()
+        types = sorted(profile.all_types())
+        marker = " (+core)" if profile.include_core_types else ""
+        print(f"{name}{marker}: {profile.description}")
+        print(f"  types: {', '.join(types)}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="typedmem", description="Schema-aware memory for AI agents.")
+    p.add_argument("--store", type=Path, default=_default_store_path(),
+                   help="path to .db (SQLite) or .jsonl (default: ~/.typedmem/memories.db)")
+    p.add_argument("--workspace", default="default",
+                   help="memory namespace; isolates one agent/domain from another (default: 'default')")
+    p.add_argument("--profile", default=None, choices=sorted(BUILTIN_PROFILES.keys()),
+                   help="built-in domain profile to bind (validates types and required fields)")
+    p.add_argument("--profile-file", default=None,
+                   help="path to a custom profile in .json or .yaml")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sa = sub.add_parser("add", help="add memory (auto-extract by default)")
+    sa.add_argument("text")
+    sa.add_argument("--type", help="force a single memory of this type (profile-defined names accepted)")
+    sa.add_argument("--subject")
+    sa.add_argument("--tags", nargs="*")
+    sa.add_argument("--confidence", type=float, default=1.0)
+    sa.add_argument("--document-id", help="opaque id of the source document")
+    sa.add_argument("--uri", help="URL or path to the source document")
+    sa.add_argument("--authority", type=float, help="weight in conflict resolution (default 1.0)")
+    sa.set_defaults(func=cmd_add)
+
+    ss = sub.add_parser("search", help="semantic search across stored memories")
+    ss.add_argument("query")
+    ss.add_argument("--limit", type=int, default=10)
+    ss.add_argument("--type", action="append",
+                    help="filter by type (repeatable; any profile-defined name)")
+    ss.add_argument("--tag", action="append")
+    ss.add_argument("--no-embed", action="store_true", help="use token overlap instead of embeddings")
+    ss.add_argument("--dim", type=int, default=256, help="hashing embedder dim")
+    ss.add_argument("--include-superseded", action="store_true",
+                    help="include memories that have been superseded by a newer record")
+    ss.set_defaults(func=cmd_search)
+
+    sl = sub.add_parser("list", help="list memories")
+    sl.add_argument("--type", help="filter by type (any profile-defined name)")
+    sl.add_argument("--limit", type=int, default=0)
+    sl.add_argument("--json", action="store_true")
+    sl.add_argument("--include-superseded", action="store_true")
+    sl.set_defaults(func=cmd_list)
+
+    sd = sub.add_parser("delete", help="delete a memory by id")
+    sd.add_argument("id")
+    sd.set_defaults(func=cmd_delete)
+
+    sc = sub.add_parser("compact", help="compact a JSONL store")
+    sc.set_defaults(func=cmd_compact)
+
+    sw = sub.add_parser("workspaces", help="list workspaces present in this store")
+    sw.set_defaults(func=cmd_workspaces)
+
+    sp = sub.add_parser("profiles", help="list built-in domain profiles")
+    sp.set_defaults(func=cmd_profiles)
+
+    se = sub.add_parser("evolve", help="run an Evolver over the store")
+    se.add_argument("--evolver", required=True,
+                    choices=["contradictions", "drift", "goals"],
+                    help="which evolver to run (summarize requires Python API + LLM client)")
+    se.add_argument("--apply", action="store_true",
+                    help="commit changes (drift/goals default to dry-run)")
+    se.add_argument("--threshold", type=float, default=0.85,
+                    help="goal-resolution similarity threshold (goals only)")
+    se.add_argument("--min-replaces", type=int, default=3,
+                    help="minimum REPLACE count in window to flag drift (drift only)")
+    se.add_argument("--window-days", type=float, default=30.0,
+                    help="trailing window for drift detection (drift only)")
+    se.add_argument("--dim", type=int, default=256,
+                    help="hashing embedder dim (goals only)")
+    se.set_defaults(func=cmd_evolve)
+
+    sh = sub.add_parser("history", help="show evolution_history for a memory")
+    sh.add_argument("id")
+    sh.set_defaults(func=cmd_history)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    profile = _load_profile(args.profile, args.profile_file)
+    store = _open_store(args.store, args.workspace, profile)
+    try:
+        return args.func(args, store)
+    finally:
+        store.close()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

typedmem/embeddings.py

@@ -0,0 +1,86 @@
+"""Embedding providers.
+
+v0.2 ships a zero-dep ``HashingEmbeddingProvider``. The protocol is small on
+purpose so an OpenAI / sentence-transformers provider can drop in for v0.3.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+from typing import Iterable, Protocol
+
+
+class EmbeddingProvider(Protocol):
+    @property
+    def id(self) -> str: ...
+    @property
+    def dim(self) -> int: ...
+    def embed(self, texts: Iterable[str]) -> list[list[float]]: ...
+
+
+_TOKEN = re.compile(r"[a-z0-9]+")
+
+
+def _ngrams(tokens: list[str], n: int) -> list[str]:
+    if len(tokens) < n:
+        return tokens[:]
+    return [" ".join(tokens[i : i + n]) for i in range(len(tokens) - n + 1)]
+
+
+class HashingEmbeddingProvider:
+    """Feature-hashing embedder over word unigrams + bigrams.
+
+    Trick is the standard `hash(token) % dim` projection; the sign is taken
+    from a second hash to keep the expectation unbiased. Vectors are L2-
+    normalized so cosine similarity reduces to a dot product."""
+
+    def __init__(self, dim: int = 256, ngram: int = 2) -> None:
+        if dim <= 0:
+            raise ValueError("dim must be positive")
+        if ngram < 1:
+            raise ValueError("ngram must be >= 1")
+        self._dim = dim
+        self._ngram = ngram
+
+    @property
+    def id(self) -> str:
+        return f"hashing:dim={self._dim};ngram={self._ngram}"
+
+    @property
+    def dim(self) -> int:
+        return self._dim
+
+    def embed(self, texts: Iterable[str]) -> list[list[float]]:
+        return [self._embed_one(t) for t in texts]
+
+    def _embed_one(self, text: str) -> list[float]:
+        tokens = _TOKEN.findall(text.lower())
+        if not tokens:
+            return [0.0] * self._dim
+        features: list[str] = []
+        for n in range(1, self._ngram + 1):
+            features.extend(_ngrams(tokens, n))
+        v = [0.0] * self._dim
+        for f in features:
+            h = hashlib.blake2b(f.encode("utf-8"), digest_size=8).digest()
+            idx = int.from_bytes(h[:4], "little") % self._dim
+            sign = 1.0 if (h[4] & 1) else -1.0
+            v[idx] += sign
+        norm = math.sqrt(sum(x * x for x in v))
+        if norm == 0:
+            return v
+        return [x / norm for x in v]
+
+
+def cosine(a: list[float], b: list[float]) -> float:
+    if not a or not b or len(a) != len(b):
+        return 0.0
+    # Both are unit-norm from HashingEmbeddingProvider, but don't assume it.
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(x * x for x in b))
+    if na == 0 or nb == 0:
+        return 0.0
+    return dot / (na * nb)

typedmem/evolvers/__init__.py

@@ -0,0 +1,23 @@
+"""Memory Evolution layer (v0.4c).
+
+Evolvers operate on existing memories — symmetric to Extractors which operate
+on text. Every evolver returns an ``EvolutionResult`` whose ``records`` are
+the audit trail of what was (or would be) done."""
+
+from .base import EvolutionRecord, EvolutionResult, Evolver, annotate_history
+from .contradictions import ContradictionSurfacer
+from .drift import PreferenceDriftDetector
+from .goals import GoalResolver, revert as revert_goal_resolution
+from .summary import SummaryEvolver
+
+__all__ = [
+    "ContradictionSurfacer",
+    "EvolutionRecord",
+    "EvolutionResult",
+    "Evolver",
+    "GoalResolver",
+    "PreferenceDriftDetector",
+    "SummaryEvolver",
+    "annotate_history",
+    "revert_goal_resolution",
+]

typedmem/evolvers/base.py

@@ -0,0 +1,84 @@
+"""Evolver protocol and audit primitives.
+
+An ``Evolver`` reads (and optionally mutates) a store, producing a list of
+``EvolutionRecord``s that explain every action taken. This audit trail is the
+load-bearing piece of v0.4c — without it, an Evolver is a black box that
+silently rewrites state, which destroys trust. Every mutating evolver also
+appends the same record to ``memory.metadata["evolution_history"]`` so the
+provenance travels with the data.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Iterator, Protocol, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..stores.base import MemoryStore
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+# Cap on metadata["evolution_history"] length. Oldest entries are dropped past
+# this. Users who need full history will use v0.5's dedicated log table.
+_HISTORY_CAP = 50
+
+
+@dataclass
+class EvolutionRecord:
+    evolver: str
+    action: str                                  # flag|annotate|create|resolve|supersede
+    input_ids: list[str]                         # memories that triggered the action
+    output_ids: list[str] = field(default_factory=list)
+    reason: str = ""
+    timestamp: datetime = field(default_factory=_now)
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["timestamp"] = self.timestamp.isoformat()
+        return d
+
+
+@dataclass
+class EvolutionResult:
+    evolver: str
+    records: list[EvolutionRecord]
+    dry_run: bool
+
+    def __len__(self) -> int:
+        return len(self.records)
+
+    def __iter__(self) -> Iterator[EvolutionRecord]:
+        return iter(self.records)
+
+    def summary(self) -> str:
+        prefix = "[dry-run] " if self.dry_run else ""
+        if not self.records:
+            return f"{prefix}{self.evolver}: 0 actions"
+        return f"{prefix}{self.evolver}: " + ", ".join(
+            f"{r.action}({len(r.input_ids)}→{len(r.output_ids)})"
+            for r in self.records
+        )
+
+
+class Evolver(Protocol):
+    name: str
+    def evolve(
+        self,
+        store: "MemoryStore",
+        *,
+        workspace: str | None = None,
+        dry_run: bool = False,
+    ) -> EvolutionResult: ...
+
+
+def annotate_history(memory, record: EvolutionRecord) -> None:
+    """Append an EvolutionRecord to a memory's metadata audit trail.
+    Capped at _HISTORY_CAP entries — oldest are dropped past that."""
+    history = memory.metadata.setdefault("evolution_history", [])
+    history.append(record.to_dict())
+    if len(history) > _HISTORY_CAP:
+        del history[:-_HISTORY_CAP]

typedmem/evolvers/contradictions.py

@@ -0,0 +1,82 @@
+"""ContradictionSurfacer: walk the FLAG-generated contradiction graph.
+
+Pure read — never mutates the store. Returns one EvolutionRecord per
+connected component of two or more memories. ``dry_run`` is irrelevant
+(reported as True) because this evolver has no side effects.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import EvolutionRecord, EvolutionResult
+
+if TYPE_CHECKING:
+    from ..stores.base import MemoryStore
+
+
+def _collect_edges(memories) -> dict[str, set[str]]:
+    """Return id → set of ids it conflicts with, restricted to memories
+    actually present in the iterable (defensive against dangling references)."""
+    by_id = {m.id: m for m in memories}
+    edges: dict[str, set[str]] = {mid: set() for mid in by_id}
+    for m in by_id.values():
+        for other_id in m.metadata.get("conflicts_with", []):
+            if other_id in by_id:
+                edges[m.id].add(other_id)
+                edges[other_id].add(m.id)
+    return edges
+
+
+def _connected_components(edges: dict[str, set[str]]) -> list[list[str]]:
+    seen: set[str] = set()
+    components: list[list[str]] = []
+    for node in edges:
+        if node in seen:
+            continue
+        # BFS from node
+        stack = [node]
+        component: list[str] = []
+        while stack:
+            cur = stack.pop()
+            if cur in seen:
+                continue
+            seen.add(cur)
+            component.append(cur)
+            stack.extend(edges[cur] - seen)
+        if len(component) > 1:
+            components.append(sorted(component))
+    return components
+
+
+class ContradictionSurfacer:
+    name = "contradiction_surfacer"
+
+    def evolve(
+        self,
+        store: "MemoryStore",
+        *,
+        workspace: str | None = None,
+        dry_run: bool = False,
+    ) -> EvolutionResult:
+        ws = workspace if workspace is not None else store.default_workspace
+        memories = [m for m in store if m.workspace == ws]
+        edges = _collect_edges(memories)
+        components = _connected_components(edges)
+        records = [
+            EvolutionRecord(
+                evolver=self.name,
+                action="flag",
+                input_ids=list(component),
+                reason=f"{len(component)} memories cross-link via conflicts_with",
+            )
+            for component in components
+        ]
+        # Always dry_run=True semantically — surfacer is read-only.
+        return EvolutionResult(self.name, records, dry_run=True)
+
+    def clusters(self, store: "MemoryStore", *, workspace: str | None = None):
+        """Convenience: return clusters as lists of Memory objects."""
+        result = self.evolve(store, workspace=workspace)
+        by_id = {m.id: m for m in store}
+        return [[by_id[i] for i in r.input_ids if i in by_id] for r in result.records]