Memory

Zil agents can have long-term memory — durable knowledge that persists across sessions and, optionally, is shared across a fleet of agents. Memory is a framework-neutral layer: the same configuration works regardless of which agent framework backs your runtime.

Scope model

Memory is organized into three scopes:

AGENT scope is the cross-agent shared pool: any agent that sets the same namespace and connects to the same memory backend sees the same knowledge. It is not keyed by user — shared facts are visible to every user and session.

Enabling memory

Add a spec.memory field to your manifest pointing at a memory adapter file:

# manifest.yaml
spec:
  memory: ./adapters/memory.yaml

Then create the adapter:

# adapters/memory.yaml
provider: mem0
mode: managed
namespace: coding
scopes: [session, user, agent]
 
retention:
  user: 90d
  agent: 180d
 
persist:
  strategy: explicit        # only store facts the agent explicitly marks
  marker: "MEMORY:"         # token the agent emits to commit a durable fact
  exclude_pii: false        # scrub PII before writing when true
 
# Optional: ship baseline knowledge (AGENT scope), installed idempotently.
seed:
  file: ../memory/seed.yaml

Install the provider dependency:

uv pip install 'zil-ai[memory]'

Fields

Providers

Mem0 (managed)

The default. Uses the Mem0  managed API. Configure via environment variables:

Mem0 (self-hosted)

Point Zil at a privately deployed Mem0 server instead of the SaaS endpoint. The host can come from the adapter (host:) or the environment; the API key still comes from MEM0_API_KEY.

# adapters/memory.yaml
provider: mem0
host: https://mem0.my-vpc.internal

The adapter host: takes precedence over MEM0_API_BASE, which takes precedence over MEM0_HOST.

Seeding

Ship an agent with baseline knowledge using a seed file. Seeds are written to AGENT scope, installed idempotently on startup (content-hash deduplication, so repeated deploys don’t duplicate), and PII-filtered at both pack time and runtime.

# memory/seed.yaml
memories:
  - topic: git
    content: >
      Commit with clear messages that reference the Jira ticket key, push to a
      feature branch, and open a pull request against the configured base branch.
  - topic: workflow
    content: >
      Never execute code changes without an approved plan; present the plan and
      wait for explicit approval.

Persistence strategies

Explicit marker

With strategy: explicit, only facts the agent explicitly marks are stored. The agent emits the configured marker token to commit a durable fact:

MEMORY: The team deploys to production only on Tuesdays and Thursdays.

Marked facts are deduplicated per session so a repeated statement is written once. Keep marked facts concise and durable — transient or ticket-specific context should not be marked.

PII filtering

Set exclude_pii: true to scrub emails, phone numbers, SSNs, card numbers, and IP addresses from content before it is written to the backend. Filtering is applied on the write path and during seed export.

Recall and persistence

How memory is wired depends on the framework backend:

• OpenHands — before each turn, relevant memories are retrieved and injected as a context preamble; after the turn completes, the exchange is persisted. This is wired at the SDK boundary because OpenHands has no pluggable memory service.
• ADK — memory is wired through the framework’s session/memory hooks, with per-session deduplication of explicitly-marked facts.

In both cases, AGENT-scope recall queries by namespace only, so shared and seeded knowledge is visible across every user and session.