> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sense-lab.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Provenance

> How AMFS tracks who wrote what, and when.

Every memory entry in AMFS carries **provenance** — metadata about who wrote it and when. This creates an audit trail and enables agents to assess the trustworthiness of information.

***

## Provenance Fields

| Field          | Type        | Description                                             |
| :------------- | :---------- | :------------------------------------------------------ |
| `agent_id`     | `str`       | The agent that wrote the entry (e.g., `"review-agent"`) |
| `session_id`   | `str`       | The session in which it was written                     |
| `written_at`   | `datetime`  | UTC timestamp of when the entry was created             |
| `pattern_refs` | `list[str]` | Cross-reference tags linking to related entries         |

***

## Automatic Provenance

Provenance is recorded automatically. You don't need to set it manually:

```python theme={null}
mem = AgentMemory(agent_id="review-agent")
entry = mem.write("svc", "finding", "potential memory leak")

print(entry.provenance.agent_id)    # "review-agent"
print(entry.provenance.session_id)  # auto-generated UUID
print(entry.provenance.written_at)  # 2025-06-15T10:30:00+00:00
```

***

## Pattern References

Use `pattern_refs` to cross-reference related entries:

```python theme={null}
mem.write(
    "checkout-service",
    "risk-timeout",
    "HTTP client has no timeout configured",
    pattern_refs=["timeout-patterns", "checkout-service/risk-latency"],
)
```

Pattern refs are free-form strings. Use them to build a web of related knowledge that agents can follow.

***

## Agent Identity

In the MCP server, agent identity is auto-detected from the environment:

| Environment | Agent ID Format          |
| :---------- | :----------------------- |
| Cursor      | `cursor/<username>`      |
| Claude Code | `claude-code/<username>` |
| Other       | `agent/<username>`       |

Override with the `AMFS_AGENT_ID` environment variable:

```bash theme={null}
export AMFS_AGENT_ID="deploy-bot"
```

***

## Provenance Tiers

AMFS computes a **provenance tier** for each entry based on the agent ID and outcome history. This enables downstream systems to prioritize production-validated knowledge over manually seeded assumptions.

| Tier                   | Value | Criteria                                                                   |
| :--------------------- | :---- | :------------------------------------------------------------------------- |
| `PRODUCTION_VALIDATED` | 1     | Agent ID starts with `agent/`, `prod/`, or `prod-` AND `outcome_count > 0` |
| `PRODUCTION_OBSERVED`  | 2     | Production agent, no outcomes yet                                          |
| `DEVELOPMENT`          | 3     | Agent ID starts with `dev/`, `test/`, `dev-`, or `test-`                   |
| `MANUAL`               | 4     | Agent ID starts with `manual/`, `seed/`, or `human/`                       |

```python theme={null}
from amfs import ProvenanceTier

entry = mem.read("svc", "pattern")
if entry.provenance_tier == ProvenanceTier.PRODUCTION_VALIDATED:
    print("This memory has been validated by production outcomes")
```

The tier is a computed property — it derives from `provenance.agent_id` and `outcome_count`, not stored as a separate field.

***

## Querying by Provenance

Search for entries written by a specific agent:

```python theme={null}
results = mem.search(agent_id="review-agent")
for entry in results:
    print(f"{entry.key} by {entry.provenance.agent_id}")
```