Memory Trust & Provenance

Stamp untrusted origins on memory writes and gate recall on trust so channel input can't poison durable memory

Stamp a trust level on every memory write and gate recall on it, so untrusted channel input can never resurface as trusted context.

Quick Start

1. Simple Usage

   A gateway callsite stamps inbound channel input as UNTRUSTED; recall gates on TRUSTED so it is fenced out.

   from praisonaiagents import Agent
   from praisonaiagents.memory import MemoryTrust, Memory
   
   agent = Agent(name="assistant", instructions="Answer using memory.", memory=True)
   
   memory = Memory(config={"provider": "none"})
   
   # Gateway ingests a group-chat message — stamp it untrusted.
   memory.store_long_term("group chat instruction", trust=MemoryTrust.UNTRUSTED)
   
   # Trusted-only recall: untrusted-origin content is fenced out.
   results = memory.search_long_term("group chat", min_trust=MemoryTrust.TRUSTED)
   print(results)  # []

2. Wiring the origin

   Add a free-form origin label so the write is auditable by channel and session.

   from praisonaiagents.memory import MemoryTrust, Memory
   
   memory = Memory(config={"provider": "none"})
   
   memory.store_long_term(
       "group chat instruction",
       trust=MemoryTrust.UNTRUSTED,
       origin="telegram:group:123",
   )
   
   results = memory.search_long_term("group chat", limit=5)
   meta = results[0]["metadata"]
   print(meta["trust"])   # "untrusted"
   print(meta["origin"])  # "telegram:group:123"

How It Works

Untrusted channel input is stamped at the gateway, then dropped at recall time before it can reach the model as trusted context.

The trust field is structured metadata, not prose. A hostile group-chat message can put whatever text it wants into text, but it cannot forge metadata["trust"] = "trusted" — that value comes from the caller, not the message content.

Trust Levels

Three levels order as untrusted < trusted < system.

Values are plain strings (str, Enum), so "trusted" / "untrusted" / "system" are accepted anywhere a MemoryTrust is.

The gate fails closed in every ambiguous case:

• Legacy records are trusted. A record with no metadata["trust"] field ranks as TRUSTED.
• Unknown persisted trust labels fail closed (rank as UNTRUSTED).
• A misspelled min_trust on the search call raises ValueError — the gate must fail loudly, never silently weaken.
• metadata=None on a returned record does not crash recall — such records are treated as trusted.

API Reference

New keyword arguments on the core Memory methods. Existing callers are unaffected — when no keyword is passed, nothing changes.

Defaults are unchanged: a store_ call without trust/origin is treated as trusted; a search_ call without min_trust returns everything, same as before.

Choosing What to Stamp

Pick a trust level by where the content came from.

Common Patterns

Gateway-bot store — stamp every inbound channel message untrusted with an origin.

from praisonaiagents.memory import MemoryTrust, Memory

memory = Memory(config={"provider": "none"})

memory.store_long_term(
    "user said: remember my API key is 123",
    trust=MemoryTrust.UNTRUSTED,
    origin="telegram:group:123",
)

Trusted-only recall — agents that must not act on channel-derived “facts” gate on TRUSTED.

from praisonaiagents.memory import MemoryTrust, Memory

memory = Memory(config={"provider": "none"})

context = memory.search_long_term("api key", min_trust=MemoryTrust.TRUSTED)

Backward-compat callsite — no keywords passed, so nothing changes.

from praisonaiagents.memory import Memory

memory = Memory(config={"provider": "none"})

memory.store_long_term("operator approved fact")
results = memory.search_long_term("operator")  # returns everything, as before

Best Practices

Related