memtrail 0.1.0__py3-none-any.whl

memtrail/__init__.py

@@ -0,0 +1,7 @@
+"""memtrail — audit and time-travel for AI agent memory."""
+
+from memtrail.api import MemTrail
+from memtrail.types import Commit, Fact, Snapshot, Diff
+
+__version__ = "0.1.0"
+__all__ = ["MemTrail", "Commit", "Fact", "Snapshot", "Diff", "__version__"]

memtrail/api.py

@@ -0,0 +1,307 @@
+"""High-level memtrail API."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterable, Optional, Union
+
+from memtrail.store import Store, default_db_path
+from memtrail.types import (
+    Commit,
+    Diff,
+    Fact,
+    Snapshot,
+    compute_commit_hash,
+)
+
+
+HEAD_REF = "HEAD"
+DEFAULT_BRANCH = "main"
+
+FactInput = Union[Fact, dict]
+
+
+def _coerce_fact(x: FactInput) -> Fact:
+    if isinstance(x, Fact):
+        return x
+    if not isinstance(x, dict):
+        raise TypeError(f"expected Fact or dict, got {type(x).__name__}")
+    if "id" not in x or "content" not in x:
+        raise ValueError("fact dict requires 'id' and 'content' keys")
+    return Fact(id=x["id"], content=x["content"], metadata=dict(x.get("metadata") or {}))
+
+
+def _utcnow_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+class MemTrail:
+    """A versioned memory repo.
+
+    >>> mt = MemTrail("my-agent")
+    >>> c = mt.commit(facts=[{"id": "user.tz", "content": "PST"}],
+    ...               message="...", author="agent")
+    >>> mt.blame("user.tz") == c
+    True
+    """
+
+    def __init__(self, repo_name: str, db_path: Optional[Union[str, Path]] = None):
+        self.repo_name = repo_name
+        self.db_path = Path(db_path) if db_path else default_db_path(repo_name)
+        self._store = Store(self.db_path)
+
+    # ---- write ----
+
+    def commit(
+        self,
+        facts: Optional[Iterable[FactInput]] = None,
+        *,
+        remove: Optional[Iterable[str]] = None,
+        message: str = "",
+        author: str = "unknown",
+        timestamp: Optional[str] = None,
+    ) -> Commit:
+        """Create a new commit.
+
+        `facts` are upserted onto the parent snapshot (matched by id).
+        `remove` is an iterable of fact ids to drop.
+        If both are None / empty, the snapshot is unchanged but a commit is still recorded.
+        """
+        parent = self.head()
+        base = self._store.get_snapshot(parent.snapshot_hash) if parent else Snapshot.empty()
+        new_snapshot = self._apply_patch(base, facts or [], remove or [])
+        return self._record_commit(
+            parent=parent,
+            snapshot=new_snapshot,
+            message=message,
+            author=author,
+            timestamp=timestamp,
+        )
+
+    def commit_snapshot(
+        self,
+        facts: Iterable[FactInput],
+        *,
+        message: str = "",
+        author: str = "unknown",
+        timestamp: Optional[str] = None,
+    ) -> Commit:
+        """Create a commit whose snapshot is exactly the given facts (full replace)."""
+        snapshot = Snapshot(facts=tuple(_coerce_fact(f) for f in facts))
+        return self._record_commit(
+            parent=self.head(),
+            snapshot=snapshot,
+            message=message,
+            author=author,
+            timestamp=timestamp,
+        )
+
+    def revert(
+        self,
+        commit_ref: str,
+        *,
+        message: Optional[str] = None,
+        author: str = "unknown",
+    ) -> Commit:
+        """Create a new commit restoring the snapshot at `commit_ref`."""
+        target = self._resolve(commit_ref)
+        if target is None:
+            raise ValueError(f"unknown commit: {commit_ref}")
+        snapshot = self._store.get_snapshot(target.snapshot_hash)
+        if snapshot is None:
+            raise RuntimeError(f"snapshot missing for commit {target.short()}")
+        return self._record_commit(
+            parent=self.head(),
+            snapshot=snapshot,
+            message=message or f"revert to {target.short()}: {target.message}",
+            author=author,
+        )
+
+    # ---- read ----
+
+    def head(self) -> Optional[Commit]:
+        h = self._store.get_ref(HEAD_REF)
+        return self._store.get_commit(h) if h else None
+
+    def log(self, limit: Optional[int] = 50, *, branch: Optional[str] = None) -> list[Commit]:
+        """Return commits along the ancestry of `branch` (default HEAD), newest first."""
+        start_hash = self._store.get_ref(branch) if branch else self._store.get_ref(HEAD_REF)
+        if not start_hash:
+            return []
+        out: list[Commit] = []
+        for c in self._store.walk_ancestors(start_hash):
+            out.append(c)
+            if limit is not None and len(out) >= limit:
+                break
+        return out
+
+    def show(self, commit_ref: str) -> Optional[Snapshot]:
+        c = self._resolve(commit_ref)
+        if not c:
+            return None
+        return self._store.get_snapshot(c.snapshot_hash)
+
+    def get_commit(self, commit_ref: str) -> Optional[Commit]:
+        return self._resolve(commit_ref)
+
+    def blame(
+        self,
+        fact_id: str,
+        *,
+        origin: bool = False,
+        at: Optional[str] = None,
+    ) -> Optional[Commit]:
+        """Find the commit that introduced or last touched `fact_id`.
+
+        - If `origin` is True, return the commit where the fact first appeared.
+        - Otherwise, return the most recent commit whose snapshot changed the
+          fact's content (or introduced it). This matches `git blame` semantics.
+        - If `at` is given, blame is computed relative to that commit's history,
+          not HEAD.
+        """
+        start = self._resolve(at) if at else self.head()
+        if start is None:
+            return None
+
+        # Walk newest -> oldest. The first commit (newest) where the fact's
+        # content differs from its parent's value is the "last touch."
+        prev_content_marker = object()
+        last_touch: Optional[Commit] = None
+        introducing: Optional[Commit] = None
+
+        # Collect ancestry oldest -> newest for clean comparison.
+        ancestry: list[Commit] = list(self._store.walk_ancestors(start.hash))
+        ancestry.reverse()
+
+        prev_value = prev_content_marker  # sentinel meaning "no prior snapshot"
+        for c in ancestry:
+            snap = self._store.get_snapshot(c.snapshot_hash)
+            cur_fact = snap.get(fact_id) if snap else None
+            cur_value = cur_fact.content if cur_fact is not None else None
+            cur_present = cur_fact is not None
+
+            if cur_present and prev_value is prev_content_marker:
+                introducing = c
+                last_touch = c
+            elif cur_present and not _content_eq(prev_value, cur_value):
+                if introducing is None:
+                    introducing = c
+                last_touch = c
+            # if removed (prev_present, not cur_present), we don't update
+            # last_touch — `blame` answers "when was this value put here."
+
+            if cur_present:
+                prev_value = cur_value
+            else:
+                prev_value = prev_content_marker  # gap: a re-introduction will be a new origin
+
+        return introducing if origin else last_touch
+
+    def diff(self, a_ref: str, b_ref: str) -> Diff:
+        a = self.show(a_ref) or Snapshot.empty()
+        b = self.show(b_ref) or Snapshot.empty()
+        return _diff_snapshots(a, b)
+
+    def list_facts(self, commit_ref: Optional[str] = None) -> list[Fact]:
+        """Return facts in the snapshot at `commit_ref` (default HEAD)."""
+        target = self._resolve(commit_ref) if commit_ref else self.head()
+        if not target:
+            return []
+        snap = self._store.get_snapshot(target.snapshot_hash)
+        return list(snap.facts) if snap else []
+
+    # ---- internal ----
+
+    def _resolve(self, ref: str) -> Optional[Commit]:
+        """Resolve a ref string to a Commit. Accepts: full hash, short hash, ref name."""
+        if not ref:
+            return None
+        if ref == HEAD_REF:
+            return self.head()
+        # Try as ref name first.
+        named = self._store.get_ref(ref)
+        if named:
+            return self._store.get_commit(named)
+        # Otherwise assume it's a (possibly short) hash.
+        return self._store.get_commit(ref)
+
+    def _record_commit(
+        self,
+        *,
+        parent: Optional[Commit],
+        snapshot: Snapshot,
+        message: str,
+        author: str,
+        timestamp: Optional[str] = None,
+    ) -> Commit:
+        ts = timestamp or _utcnow_iso()
+        snap_hash = self._store.put_snapshot(snapshot)
+        commit_hash = compute_commit_hash(
+            parent_hash=parent.hash if parent else None,
+            snapshot_hash=snap_hash,
+            author=author,
+            message=message,
+            timestamp=ts,
+        )
+        commit = Commit(
+            hash=commit_hash,
+            parent_hash=parent.hash if parent else None,
+            snapshot_hash=snap_hash,
+            author=author,
+            message=message,
+            timestamp=ts,
+        )
+        self._store.put_commit(commit)
+        self._store.set_ref(HEAD_REF, commit.hash)
+        if parent is None:
+            self._store.set_ref(DEFAULT_BRANCH, commit.hash)
+        else:
+            current_branch_head = self._store.get_ref(DEFAULT_BRANCH)
+            if current_branch_head == parent.hash:
+                self._store.set_ref(DEFAULT_BRANCH, commit.hash)
+        return commit
+
+    @staticmethod
+    def _apply_patch(
+        base: Snapshot,
+        upserts: Iterable[FactInput],
+        removes: Iterable[str],
+    ) -> Snapshot:
+        by_id: dict[str, Fact] = {f.id: f for f in base.facts}
+        for u in upserts:
+            f = _coerce_fact(u)
+            by_id[f.id] = f
+        for rid in removes:
+            by_id.pop(rid, None)
+        return Snapshot(facts=tuple(by_id.values()))
+
+    def close(self) -> None:
+        self._store.close()
+
+    def __enter__(self) -> "MemTrail":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+
+def _content_eq(a, b) -> bool:
+    """Compare fact contents structurally."""
+    return a == b
+
+
+def _diff_snapshots(a: Snapshot, b: Snapshot) -> Diff:
+    a_by_id = {f.id: f for f in a.facts}
+    b_by_id = {f.id: f for f in b.facts}
+    a_ids = set(a_by_id)
+    b_ids = set(b_by_id)
+    added = tuple(b_by_id[i] for i in sorted(b_ids - a_ids))
+    removed = tuple(a_by_id[i] for i in sorted(a_ids - b_ids))
+    changed = tuple(
+        (a_by_id[i], b_by_id[i])
+        for i in sorted(a_ids & b_ids)
+        if not _content_eq(a_by_id[i].content, b_by_id[i].content)
+        or a_by_id[i].metadata != b_by_id[i].metadata
+    )
+    return Diff(added=added, removed=removed, changed=changed)

memtrail/cli.py

@@ -0,0 +1,186 @@
+"""memtrail CLI.
+
+Usage:
+    memtrail --repo <name> log [--limit N]
+    memtrail --repo <name> show <commit>
+    memtrail --repo <name> blame <fact_id> [--origin]
+    memtrail --repo <name> diff <a> <b>
+    memtrail --repo <name> revert <commit> [--message MSG]
+    memtrail --repo <name> facts [<commit>]
+    memtrail --repo <name> commit --fact id=value [...] [--remove id ...] -m MSG [--author A]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Optional
+
+from memtrail import MemTrail, __version__
+
+
+def _make_repo_parent() -> argparse.ArgumentParser:
+    """A parent parser exposing --repo / --db. Subcommands inherit it via `parents=`."""
+    parent = argparse.ArgumentParser(add_help=False)
+    parent.add_argument(
+        "--repo",
+        default="default",
+        help="Repo name (default: 'default'). Stored at ~/.memtrail/<repo>.db",
+    )
+    parent.add_argument(
+        "--db",
+        default=None,
+        help="Override the database path entirely.",
+    )
+    return parent
+
+
+def _open(args) -> MemTrail:
+    return MemTrail(args.repo, db_path=args.db)
+
+
+def _print_commit_line(c) -> None:
+    print(f"{c.short()}  {c.timestamp}  {c.author:<24}  {c.message}")
+
+
+def _parse_fact_arg(s: str) -> dict:
+    """Parse `id=value` or `id=@file.json`. Plain values are stored as strings."""
+    if "=" not in s:
+        raise SystemExit(f"--fact must be id=value, got: {s!r}")
+    fid, _, raw = s.partition("=")
+    fid = fid.strip()
+    if not fid:
+        raise SystemExit(f"--fact id is empty in: {s!r}")
+    if raw.startswith("@"):
+        with open(raw[1:], "r", encoding="utf-8") as fh:
+            content = json.load(fh)
+    else:
+        try:
+            content = json.loads(raw)
+        except json.JSONDecodeError:
+            content = raw
+    return {"id": fid, "content": content}
+
+
+def cmd_log(args) -> int:
+    mt = _open(args)
+    commits = mt.log(limit=args.limit)
+    if not commits:
+        print("(no commits yet)")
+        return 0
+    for c in commits:
+        _print_commit_line(c)
+    return 0
+
+
+def cmd_show(args) -> int:
+    mt = _open(args)
+    snap = mt.show(args.commit)
+    if snap is None:
+        print(f"unknown commit: {args.commit}", file=sys.stderr)
+        return 1
+    print(json.dumps(snap.to_dict(), indent=2, ensure_ascii=False))
+    return 0
+
+
+def cmd_blame(args) -> int:
+    mt = _open(args)
+    c = mt.blame(args.fact_id, origin=args.origin)
+    if c is None:
+        print(f"no commit touches fact_id: {args.fact_id}", file=sys.stderr)
+        return 1
+    _print_commit_line(c)
+    return 0
+
+
+def cmd_diff(args) -> int:
+    mt = _open(args)
+    d = mt.diff(args.a, args.b)
+    print(json.dumps(d.to_dict(), indent=2, ensure_ascii=False))
+    return 0
+
+
+def cmd_revert(args) -> int:
+    mt = _open(args)
+    c = mt.revert(args.commit, message=args.message, author=args.author)
+    _print_commit_line(c)
+    return 0
+
+
+def cmd_facts(args) -> int:
+    mt = _open(args)
+    facts = mt.list_facts(commit_ref=args.commit)
+    if not facts:
+        print("(no facts)")
+        return 0
+    for f in sorted(facts, key=lambda x: x.id):
+        print(f"{f.id}\t{json.dumps(f.content, ensure_ascii=False)}")
+    return 0
+
+
+def cmd_commit(args) -> int:
+    mt = _open(args)
+    facts = [_parse_fact_arg(s) for s in (args.fact or [])]
+    c = mt.commit(
+        facts=facts,
+        remove=args.remove or [],
+        message=args.message,
+        author=args.author,
+    )
+    _print_commit_line(c)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="memtrail", description="Audit and time-travel for AI memory.")
+    p.add_argument("--version", action="version", version=f"memtrail {__version__}")
+    repo_parent = _make_repo_parent()
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    pl = sub.add_parser("log", parents=[repo_parent], help="List recent commits.")
+    pl.add_argument("--limit", type=int, default=20)
+    pl.set_defaults(func=cmd_log)
+
+    ps = sub.add_parser("show", parents=[repo_parent], help="Show snapshot at commit.")
+    ps.add_argument("commit")
+    ps.set_defaults(func=cmd_show)
+
+    pb = sub.add_parser("blame", parents=[repo_parent], help="Find commit that introduced/touched a fact.")
+    pb.add_argument("fact_id")
+    pb.add_argument("--origin", action="store_true", help="Return the introducing commit.")
+    pb.set_defaults(func=cmd_blame)
+
+    pd = sub.add_parser("diff", parents=[repo_parent], help="Diff two commits.")
+    pd.add_argument("a")
+    pd.add_argument("b")
+    pd.set_defaults(func=cmd_diff)
+
+    pr = sub.add_parser("revert", parents=[repo_parent], help="Revert to a prior commit (creates a new commit).")
+    pr.add_argument("commit")
+    pr.add_argument("-m", "--message", default=None)
+    pr.add_argument("--author", default="cli")
+    pr.set_defaults(func=cmd_revert)
+
+    pf = sub.add_parser("facts", parents=[repo_parent], help="List facts at a commit (default HEAD).")
+    pf.add_argument("commit", nargs="?", default=None)
+    pf.set_defaults(func=cmd_facts)
+
+    pc = sub.add_parser("commit", parents=[repo_parent], help="Create a commit from CLI input.")
+    pc.add_argument("--fact", action="append", help="Repeatable: id=value or id=@file.json")
+    pc.add_argument("--remove", action="append", help="Repeatable: fact id to remove.")
+    pc.add_argument("-m", "--message", required=True)
+    pc.add_argument("--author", default="cli")
+    pc.set_defaults(func=cmd_commit)
+
+    return p
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

memtrail/store.py

@@ -0,0 +1,188 @@
+"""SQLite-backed content-addressed store for memtrail."""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+import threading
+from pathlib import Path
+from typing import Iterator, Optional
+
+from memtrail.types import Commit, Snapshot, canonical_json
+
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS snapshots (
+    hash TEXT PRIMARY KEY,
+    content TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS commits (
+    hash TEXT PRIMARY KEY,
+    parent_hash TEXT,
+    snapshot_hash TEXT NOT NULL,
+    author TEXT NOT NULL,
+    message TEXT NOT NULL,
+    timestamp TEXT NOT NULL,
+    FOREIGN KEY (snapshot_hash) REFERENCES snapshots(hash),
+    FOREIGN KEY (parent_hash) REFERENCES commits(hash)
+);
+
+CREATE INDEX IF NOT EXISTS idx_commits_parent ON commits(parent_hash);
+CREATE INDEX IF NOT EXISTS idx_commits_timestamp ON commits(timestamp);
+
+CREATE TABLE IF NOT EXISTS refs (
+    name TEXT PRIMARY KEY,
+    commit_hash TEXT NOT NULL,
+    FOREIGN KEY (commit_hash) REFERENCES commits(hash)
+);
+"""
+
+
+def default_db_path(repo_name: str) -> Path:
+    base = Path(os.environ.get("MEMTRAIL_HOME", Path.home() / ".memtrail"))
+    base.mkdir(parents=True, exist_ok=True)
+    safe = "".join(c if c.isalnum() or c in "-_." else "_" for c in repo_name)
+    return base / f"{safe}.db"
+
+
+class Store:
+    """Thin SQLite wrapper. Thread-safe via a per-instance lock."""
+
+    def __init__(self, db_path: Path | str):
+        self.db_path = Path(db_path)
+        self._lock = threading.RLock()
+        self._conn = sqlite3.connect(str(self.db_path), check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA foreign_keys = ON")
+        self._conn.executescript(SCHEMA)
+        self._conn.commit()
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()
+
+    # ---- snapshots ----
+
+    def put_snapshot(self, snapshot: Snapshot) -> str:
+        h = snapshot.hash
+        content = canonical_json(snapshot.to_dict())
+        with self._lock:
+            self._conn.execute(
+                "INSERT OR IGNORE INTO snapshots (hash, content) VALUES (?, ?)",
+                (h, content),
+            )
+            self._conn.commit()
+        return h
+
+    def get_snapshot(self, snapshot_hash: str) -> Optional[Snapshot]:
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT content FROM snapshots WHERE hash = ?", (snapshot_hash,)
+            ).fetchone()
+        if not row:
+            return None
+        import json
+
+        return Snapshot.from_dict(json.loads(row["content"]))
+
+    # ---- commits ----
+
+    def put_commit(self, commit: Commit) -> None:
+        with self._lock:
+            self._conn.execute(
+                """
+                INSERT OR IGNORE INTO commits
+                (hash, parent_hash, snapshot_hash, author, message, timestamp)
+                VALUES (?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    commit.hash,
+                    commit.parent_hash,
+                    commit.snapshot_hash,
+                    commit.author,
+                    commit.message,
+                    commit.timestamp,
+                ),
+            )
+            self._conn.commit()
+
+    def get_commit(self, commit_hash: str) -> Optional[Commit]:
+        # Support short-hash prefix lookup (≥4 chars).
+        if len(commit_hash) < 4:
+            return None
+        with self._lock:
+            if len(commit_hash) == 64:
+                row = self._conn.execute(
+                    "SELECT * FROM commits WHERE hash = ?", (commit_hash,)
+                ).fetchone()
+            else:
+                rows = self._conn.execute(
+                    "SELECT * FROM commits WHERE hash LIKE ? LIMIT 2",
+                    (commit_hash + "%",),
+                ).fetchall()
+                if len(rows) != 1:
+                    return None
+                row = rows[0]
+        if not row:
+            return None
+        return self._row_to_commit(row)
+
+    def iter_commits_newest_first(self, limit: Optional[int] = None) -> Iterator[Commit]:
+        sql = "SELECT * FROM commits ORDER BY timestamp DESC, hash DESC"
+        if limit is not None:
+            sql += f" LIMIT {int(limit)}"
+        with self._lock:
+            rows = self._conn.execute(sql).fetchall()
+        for row in rows:
+            yield self._row_to_commit(row)
+
+    def iter_commits_oldest_first(self) -> Iterator[Commit]:
+        sql = "SELECT * FROM commits ORDER BY timestamp ASC, hash ASC"
+        with self._lock:
+            rows = self._conn.execute(sql).fetchall()
+        for row in rows:
+            yield self._row_to_commit(row)
+
+    def walk_ancestors(self, commit_hash: str) -> Iterator[Commit]:
+        """Yield commit and its ancestors via parent pointers, newest first."""
+        cur = self.get_commit(commit_hash)
+        while cur is not None:
+            yield cur
+            if cur.parent_hash is None:
+                break
+            cur = self.get_commit(cur.parent_hash)
+
+    @staticmethod
+    def _row_to_commit(row: sqlite3.Row) -> Commit:
+        return Commit(
+            hash=row["hash"],
+            parent_hash=row["parent_hash"],
+            snapshot_hash=row["snapshot_hash"],
+            author=row["author"],
+            message=row["message"],
+            timestamp=row["timestamp"],
+        )
+
+    # ---- refs ----
+
+    def set_ref(self, name: str, commit_hash: str) -> None:
+        with self._lock:
+            self._conn.execute(
+                "INSERT INTO refs (name, commit_hash) VALUES (?, ?) "
+                "ON CONFLICT(name) DO UPDATE SET commit_hash = excluded.commit_hash",
+                (name, commit_hash),
+            )
+            self._conn.commit()
+
+    def get_ref(self, name: str) -> Optional[str]:
+        with self._lock:
+            row = self._conn.execute(
+                "SELECT commit_hash FROM refs WHERE name = ?", (name,)
+            ).fetchone()
+        return row["commit_hash"] if row else None
+
+    def list_refs(self) -> dict[str, str]:
+        with self._lock:
+            rows = self._conn.execute("SELECT name, commit_hash FROM refs").fetchall()
+        return {row["name"]: row["commit_hash"] for row in rows}

memtrail/tools.py

@@ -0,0 +1,242 @@
+"""Agent-callable tool adapters for memtrail.
+
+Returns tool schemas in provider-native shapes plus a `dispatch` callable that
+routes a tool invocation to the right MemTrail method.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from memtrail.api import MemTrail
+
+
+ToolSchema = dict[str, Any]
+Dispatcher = Callable[[str, dict], Any]
+
+
+def _tool_definitions() -> list[ToolSchema]:
+    """Provider-neutral tool definitions. Adapters re-shape these."""
+    return [
+        {
+            "name": "memtrail_commit",
+            "description": (
+                "Persist a memory change as a versioned commit. Use this when the "
+                "agent learns a new fact, updates an existing one, or wants to "
+                "make a memory state durable and auditable."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "facts": {
+                        "type": "array",
+                        "description": (
+                            "Facts to add or update. Each fact has a stable id, content, "
+                            "and optional metadata. Same-id facts overwrite previous values."
+                        ),
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "id": {"type": "string"},
+                                "content": {},
+                                "metadata": {"type": "object"},
+                            },
+                            "required": ["id", "content"],
+                        },
+                    },
+                    "remove": {
+                        "type": "array",
+                        "description": "Fact ids to remove from the memory.",
+                        "items": {"type": "string"},
+                    },
+                    "message": {
+                        "type": "string",
+                        "description": "Why this change is being committed.",
+                    },
+                    "author": {
+                        "type": "string",
+                        "description": "Identifier of the author (model name, user, etc.).",
+                    },
+                },
+                "required": ["message"],
+            },
+        },
+        {
+            "name": "memtrail_log",
+            "description": (
+                "List recent memory commits, newest first. Use to understand "
+                "how the memory has evolved over time."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "limit": {"type": "integer", "default": 20},
+                },
+            },
+        },
+        {
+            "name": "memtrail_show",
+            "description": (
+                "Return all facts in the memory at a specific commit (full snapshot). "
+                "Use to inspect past states."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "commit": {
+                        "type": "string",
+                        "description": "Commit hash (full or short) or ref name.",
+                    },
+                },
+                "required": ["commit"],
+            },
+        },
+        {
+            "name": "memtrail_blame",
+            "description": (
+                "Return the commit that introduced or last touched a given fact id. "
+                "Use to investigate WHY the agent believes a particular thing."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "fact_id": {"type": "string"},
+                    "origin": {
+                        "type": "boolean",
+                        "default": False,
+                        "description": (
+                            "If true, return the FIRST commit that introduced the fact. "
+                            "Default returns the most recent commit that changed it."
+                        ),
+                    },
+                },
+                "required": ["fact_id"],
+            },
+        },
+        {
+            "name": "memtrail_diff",
+            "description": (
+                "Compare two commits and return added / removed / changed facts."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "a": {"type": "string", "description": "Earlier commit hash or ref."},
+                    "b": {"type": "string", "description": "Later commit hash or ref."},
+                },
+                "required": ["a", "b"],
+            },
+        },
+        {
+            "name": "memtrail_revert",
+            "description": (
+                "Create a new commit restoring the memory state at a given commit. "
+                "Use to roll back after discovering a bad fact."
+            ),
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "commit": {"type": "string"},
+                    "message": {"type": "string"},
+                    "author": {"type": "string"},
+                },
+                "required": ["commit"],
+            },
+        },
+    ]
+
+
+def _make_dispatcher(mt: MemTrail) -> Dispatcher:
+    def dispatch(name: str, args: dict) -> Any:
+        args = args or {}
+        if name == "memtrail_commit":
+            commit = mt.commit(
+                facts=args.get("facts") or [],
+                remove=args.get("remove") or [],
+                message=args.get("message", ""),
+                author=args.get("author", "agent"),
+            )
+            return {
+                "hash": commit.hash,
+                "short": commit.short(),
+                "parent": commit.parent_hash,
+                "timestamp": commit.timestamp,
+                "message": commit.message,
+                "author": commit.author,
+            }
+        if name == "memtrail_log":
+            limit = int(args.get("limit", 20))
+            return [
+                {
+                    "hash": c.hash,
+                    "short": c.short(),
+                    "parent": c.parent_hash,
+                    "timestamp": c.timestamp,
+                    "author": c.author,
+                    "message": c.message,
+                }
+                for c in mt.log(limit=limit)
+            ]
+        if name == "memtrail_show":
+            snap = mt.show(args["commit"])
+            if snap is None:
+                return {"error": f"unknown commit: {args['commit']}"}
+            return snap.to_dict()
+        if name == "memtrail_blame":
+            commit = mt.blame(args["fact_id"], origin=bool(args.get("origin", False)))
+            if commit is None:
+                return {"error": f"no commit found for fact_id: {args['fact_id']}"}
+            return {
+                "hash": commit.hash,
+                "short": commit.short(),
+                "timestamp": commit.timestamp,
+                "author": commit.author,
+                "message": commit.message,
+            }
+        if name == "memtrail_diff":
+            return mt.diff(args["a"], args["b"]).to_dict()
+        if name == "memtrail_revert":
+            commit = mt.revert(
+                args["commit"],
+                message=args.get("message"),
+                author=args.get("author", "agent"),
+            )
+            return {
+                "hash": commit.hash,
+                "short": commit.short(),
+                "message": commit.message,
+            }
+        raise ValueError(f"unknown tool: {name}")
+
+    return dispatch
+
+
+def anthropic_tools(mt: MemTrail) -> tuple[list[ToolSchema], Dispatcher]:
+    """Return (tools, dispatch) shaped for Anthropic's `messages.create(tools=...)`."""
+    out: list[ToolSchema] = []
+    for t in _tool_definitions():
+        out.append(
+            {
+                "name": t["name"],
+                "description": t["description"],
+                "input_schema": t["parameters"],
+            }
+        )
+    return out, _make_dispatcher(mt)
+
+
+def openai_tools(mt: MemTrail) -> tuple[list[ToolSchema], Dispatcher]:
+    """Return (tools, dispatch) shaped for OpenAI's `chat.completions(tools=...)`."""
+    out: list[ToolSchema] = []
+    for t in _tool_definitions():
+        out.append(
+            {
+                "type": "function",
+                "function": {
+                    "name": t["name"],
+                    "description": t["description"],
+                    "parameters": t["parameters"],
+                },
+            }
+        )
+    return out, _make_dispatcher(mt)

memtrail/types.py

@@ -0,0 +1,125 @@
+"""Core data types for memtrail."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field, asdict
+from typing import Any, Optional
+
+
+def canonical_json(obj: Any) -> str:
+    """Stable JSON serialization for content-addressing."""
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def content_hash(obj: Any) -> str:
+    """SHA-256 of canonical JSON. Returned as a 64-char hex string."""
+    return hashlib.sha256(canonical_json(obj).encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True)
+class Fact:
+    """An atomic memory item. Caller-provided `id` enables targeted blame."""
+
+    id: str
+    content: Any
+    metadata: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {"id": self.id, "content": self.content, "metadata": dict(self.metadata)}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Fact":
+        return cls(id=d["id"], content=d["content"], metadata=dict(d.get("metadata") or {}))
+
+
+@dataclass(frozen=True)
+class Snapshot:
+    """A set of facts at a point in time. Hashed by canonical JSON of sorted facts."""
+
+    facts: tuple[Fact, ...]
+
+    @property
+    def hash(self) -> str:
+        return content_hash([f.to_dict() for f in self._sorted()])
+
+    def _sorted(self) -> list[Fact]:
+        return sorted(self.facts, key=lambda f: f.id)
+
+    def get(self, fact_id: str) -> Optional[Fact]:
+        for f in self.facts:
+            if f.id == fact_id:
+                return f
+        return None
+
+    def ids(self) -> set[str]:
+        return {f.id for f in self.facts}
+
+    def to_dict(self) -> dict:
+        return {"facts": [f.to_dict() for f in self._sorted()]}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Snapshot":
+        return cls(facts=tuple(Fact.from_dict(x) for x in d.get("facts", [])))
+
+    @classmethod
+    def empty(cls) -> "Snapshot":
+        return cls(facts=())
+
+
+@dataclass(frozen=True)
+class Commit:
+    """A versioned snapshot. `hash` is content-addressed over the commit metadata + snapshot."""
+
+    hash: str
+    parent_hash: Optional[str]
+    snapshot_hash: str
+    author: str
+    message: str
+    timestamp: str  # ISO-8601 UTC
+
+    def short(self) -> str:
+        return self.hash[:12]
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class Diff:
+    """Difference between two snapshots."""
+
+    added: tuple[Fact, ...]      # facts present in B, not A
+    removed: tuple[Fact, ...]    # facts present in A, not B
+    changed: tuple[tuple[Fact, Fact], ...]  # (before, after) for facts whose content changed
+
+    def is_empty(self) -> bool:
+        return not (self.added or self.removed or self.changed)
+
+    def to_dict(self) -> dict:
+        return {
+            "added": [f.to_dict() for f in self.added],
+            "removed": [f.to_dict() for f in self.removed],
+            "changed": [
+                {"before": a.to_dict(), "after": b.to_dict()} for a, b in self.changed
+            ],
+        }
+
+
+def compute_commit_hash(
+    parent_hash: Optional[str],
+    snapshot_hash: str,
+    author: str,
+    message: str,
+    timestamp: str,
+) -> str:
+    return content_hash(
+        {
+            "parent_hash": parent_hash,
+            "snapshot_hash": snapshot_hash,
+            "author": author,
+            "message": message,
+            "timestamp": timestamp,
+        }
+    )

memtrail-0.1.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: memtrail
+Version: 0.1.0
+Summary: Audit and time-travel for AI agent memory. log, show, blame, diff, revert — callable from inside the agent's reasoning loop.
+Author-email: Rahul Karda <rahulkarda2002@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,audit,llm,memory,versioning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Provides-Extra: cli
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# memtrail
+
+> **Audit and time-travel for AI agent memory.** A drop-in versioned backend with `log`, `show`, `blame`, `diff`, and `revert` — callable from inside the agent's reasoning loop.
+
+## Install
+
+```bash
+pip install memtrail
+```
+
+## Quickstart
+
+```python
+from memtrail import MemTrail
+
+mt = MemTrail("my-agent")
+
+# Commit a fact the agent learned
+c1 = mt.commit(
+    facts=[{"id": "user.tz", "content": "America/Los_Angeles"}],
+    message="learned user timezone from greeting",
+    author="agent",
+)
+
+# Later, investigate the memory
+mt.blame("user.tz")        # → which commit introduced this fact?
+mt.show(c1.hash)           # → full snapshot at that point
+mt.log(limit=10)           # → recent history
+mt.revert(c1.hash)         # → roll back to before a bad change
+```
+
+## Use as agent tools
+
+memtrail ships tool schemas in two shapes. The schemas describe the same six
+operations; pick whichever your model provider expects.
+
+```python
+from memtrail import MemTrail
+from memtrail.tools import anthropic_tools, openai_tools
+
+mt = MemTrail("my-agent")
+
+tools, dispatch = anthropic_tools(mt)   # input_schema shape
+# or:
+tools, dispatch = openai_tools(mt)      # function-tool shape
+
+# When the model emits a tool call, route it:
+result = dispatch(tool_name, tool_input)
+```
+
+The six tools exposed: `memtrail_commit`, `memtrail_log`, `memtrail_show`,
+`memtrail_blame`, `memtrail_diff`, `memtrail_revert`.
+
+## CLI
+
+```bash
+memtrail commit --repo my-agent --fact 'user.tz="PST"' -m "learned tz"
+memtrail log    --repo my-agent
+memtrail show   --repo my-agent <commit>
+memtrail blame  --repo my-agent <fact_id>
+memtrail diff   --repo my-agent <commit_a> <commit_b>
+memtrail revert --repo my-agent <commit>
+memtrail facts  --repo my-agent           # list facts at HEAD
+```
+
+Repo state lives at `~/.memtrail/<repo>.db` by default. Override with
+`--db /path/to.db` or the `MEMTRAIL_HOME` environment variable.
+
+## Data model
+
+- **Fact**: `{id, content, metadata}` — the atomic memory unit. Caller-provided `id`s enable targeted blame.
+- **Snapshot**: a set of facts at a point in time, content-addressed by SHA-256 of canonical JSON.
+- **Commit**: `{hash, parent_hash, snapshot_hash, author, message, timestamp}` — forms an append-only DAG.
+
+`commit(facts=...)` upserts onto the parent snapshot (matched by `id`). Use
+`commit(remove=[...])` to drop facts, or `commit_snapshot(facts=...)` for full
+replace.
+
+## Status
+
+`v0.1` — alpha. Zero runtime dependencies. Python ≥ 3.9.
+
+## License
+
+MIT.

memtrail-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+memtrail/__init__.py,sha256=2SwZtdvd0T3DxonSmGUOTTeMCpIt3bNx8UDBCAzzxH4,252
+memtrail/api.py,sha256=ze7rFTitc7GrHQxlszdzIZdxYxX75d0xVRy1Hh2-iU0,10388
+memtrail/cli.py,sha256=XodgQRl5LIlQtYoqOnp9rFxdmBvvf44a1NTeMWUgKLo,5704
+memtrail/store.py,sha256=1eaWG7zpfX_oF5-h2W5G5own4IAHi_cIgxDorkKHkuY,6208
+memtrail/tools.py,sha256=yFNUKF8WqOcq4BvBtmHBsdpVmfHw8T9n3slG8z2vvrU,8716
+memtrail/types.py,sha256=TJUZ73zaWqpm87v2yPsQunU3eQdY-BghcCyMRliFUcE,3404
+memtrail-0.1.0.dist-info/METADATA,sha256=J-8hCszMTsswP-P3jrHmaMQMQFDXG9_C-Uz4p59-bTY,3581
+memtrail-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+memtrail-0.1.0.dist-info/entry_points.txt,sha256=6v8-8ytJXkpiIOgycEpmMLqf83BNPLJbkpcK0ymuhsc,47
+memtrail-0.1.0.dist-info/licenses/LICENSE,sha256=iHR4fQx3If46fsGTjlhYxqY6rodQDjlQN9S9b3PpyjM,1068
+memtrail-0.1.0.dist-info/RECORD,,

memtrail-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

memtrail-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+memtrail = memtrail.cli:main

memtrail-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rahul Karda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.