Provenance & review-status metadata convention (governed "agent memory")

[imonroe]

Summary

Adopt a lightweight, documented metadata convention for provenance and review status on memories — source reference, confidence, and a review state — and expose it through the REST/MCP layers and search filters.

Idea from OB1

OB1's schemas/agent-memory describes "sidecar tables that turn existing thoughts into governed, provenance-labeled operational memory for agent workflows," with related schemas for provenance-chains and thought-audit. The concepts: track where a memory came from, attach a confidence/review policy, and keep an audit trail so AI-generated content can be trusted or quarantined.

Why it fits memserv

• memserv already has the seed of this: agent_id is a write-only provenance tag, and mem0 maintains per-memory history (GET /api/v1/memories/{id}/history). This issue formalizes and extends it.
• Useful once the import toolkit lands: imported memories (lower trust) vs. memories Claude explicitly chose to save (higher trust) want to be distinguishable and filterable.
• Pure metadata + filter convention — no multi-tenant logic, no new datastore.

Proposed approach

• Define reserved metadata keys, e.g. source (free-form origin), confidence (e.g. high|medium|low), review_status (e.g. unreviewed|approved|rejected).
• Accept/return them in AddMemoryRequest / REST responses and the MCP add_memory tool.
• Allow REST reads to filter by these (consistent with the existing "REST may filter reads by agent_id" rule). Keep MCP reads unfiltered per the architecture invariant — all agents share one memory.
• Document the convention in docs/DEVELOPER_GUIDE.md and docs/USER_GUIDE.md.

Notes / scope

OB1 implements this as Postgres sidecar tables + RLS; memserv should NOT add tables or per-user isolation (PRD non-goals). Implement as metadata stored in the existing Qdrant payload. Full graph-style "provenance chains" / typed edges are a separate, heavier idea (see typed-edges issue) and partly conflict with the vector-only / no-graph non-goal.

Source: https://github.com/NateBJones-Projects/OB1/tree/main/schemas

[norika1207-lab]

The lightweight metadata approach fits memserv well, but I would keep review_status separate from confidence.

A memory can be high-confidence but unreviewed, or reviewed but intentionally marked low-confidence. Those are different operational states for an agent deciding whether to use it.

A small convention that might scale:

• source.kind: user, agent, import, tool, system
• source.ref: free-form pointer or URL/id
• source.agent_id: writer when agent-produced
• confidence: high, medium, low, unknown
• review_status: unreviewed, approved, rejected, stale
• reviewed_by / reviewed_at when applicable
• expires_at or valid_until for facts that age out

The expiry/stale bit is important for agent memory. The failure mode is often not “bad memory was stored”; it is “old memory stayed trusted after the world changed.”