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.
