Provenance

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:

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:

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:

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/

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:

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