Provenance

Every memory entry in SenseLab 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>`

In headless contexts — CI, scripts, servers — set the identity with an environment variable:

export AMFS_AGENT_ID="deploy-bot"

IDE signals are checked before AMFS_AGENT_ID, so the variable does not rename an agent running inside Cursor or Claude Code. That is deliberate: it stops a server-side value inherited by your shell from relabelling local sessions. Inside an IDE, call amfs_set_identity instead.

Session Metadata

Provenance answers who wrote an entry. A parallel record answers what was running — the model, the client, and the tools it had available:

Field	Description
`model`	The LLM that made the decision (e.g. `claude-4-opus`, `gpt-4o`)
`client_name` / `platform`	The client the agent ran in
`tools_available`	Tools the agent could call in that session
`mcp_client_id` / `mcp_session_id`	MCP connection identifiers

Agents set this by passing model= to amfs_set_identity. It is stored on the agent’s profile and on decision traces rather than on Provenance itself, so when you audit a decision later you can tell which model made it.

amfs_set_identity("deploy-agent", "Rolling out v2.14", model="claude-4-opus")

Provenance Tiers

SenseLab 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}")

Product

Getting Started

Guides

Self-Hosting

Core Concepts

Pro Features

Provenance Fields

Automatic Provenance

Pattern References

Agent Identity

Session Metadata

Provenance Tiers

Querying by Provenance

​Provenance Fields

​Automatic Provenance

​Pattern References

​Agent Identity

​Session Metadata

​Provenance Tiers

​Querying by Provenance

Provenance Fields

Automatic Provenance

Pattern References

Agent Identity

Session Metadata

Provenance Tiers

Querying by Provenance