Memory

Memory is small durable background context, not a transcript database or trusted config. It is off by default.

Config

createHeypi({
  state: { root: "./state" },
  // ...adapters, agent, runtime
  scope: "channel",
  memory: {
    enabled: true,
    scope: "user",
    writePolicy: "approvers",
    maxChars: 4000,
  },
});

memory.scope defaults to the top-level scope.

Options

Behavior

When enabled, heypi:

1. reads the scoped memory file,
2. injects it as background context,
3. exposes memory_read, memory_write, memory_replace, and memory_delete,
4. allows mutation according to memory.writePolicy,
5. validates memory writes for size, obvious secrets/private keys, and prompt-injection-shaped text.

Good memory:

- This channel is for production incidents.
- Deploy approvals require Alice or Bob.
- The staging API lives at https://staging.example.com.

Bad memory:

- Full chat logs.
- Temporary task state.
- Secrets or tokens.
- Untrusted instructions copied from random users.

Write validation is a hygiene check, not a security boundary. Do not store secrets, credentials, private data, or policy rules that must be trusted.

Scope

Memory scopes:

• channel: every user in the chat can share memory.
• user: each actor gets separate memory.
• adapter: every accepted chat on the adapter shares memory.
• agent: every adapter for this configured agent shares memory.

DMs use the same rules as other chats: channel memory follows the provider chat/channel id, while user memory follows the actor id.

Write policy

writePolicy controls mutation:

• auto: the agent can write, replace, and delete memory.
• approvers: only turns initiated by configured approver users or groups can mutate memory.
• off: memory can be read and injected, but cannot be changed.

Defaults:

• when adapter approvers or admins are configured: approvers.
• without approvers, channel and user: auto.
• without approvers, adapter and agent: off.

When memory is enabled, heypi logs the memory scope and write policy at startup. adapter and agent scopes are logged as warnings because they let one chat affect future answers elsewhere.

Approvals do not elevate actor identity. If a non-approver starts a turn and an approver later approves one of its tool calls, the continued turn still belongs to the original requester for memory.writePolicy checks.

Concurrent writes use the filesystem as the source of truth. Avoid concurrent writes to the same scope; no merge is attempted.