memtrail 0.1.0__tar.gz

memtrail-0.1.0/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.

memtrail-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,85 @@
+# 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/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "memtrail"
+version = "0.1.0"
+description = "Audit and time-travel for AI agent memory. log, show, blame, diff, revert — callable from inside the agent's reasoning loop."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Rahul Karda", email = "rahulkarda2002@gmail.com" }]
+keywords = ["ai", "agents", "memory", "versioning", "audit", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.optional-dependencies]
+cli = []
+dev = ["pytest>=7", "pytest-cov", "ruff"]
+
+[project.scripts]
+memtrail = "memtrail.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/memtrail"]
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "src/memtrail",
+    "tests",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+exclude = [
+    "**/__pycache__",
+    "**/*.pyc",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"

memtrail-0.1.0/src/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-0.1.0/src/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)