Persona Proposals

Agent self-evolution with human approval — the agent can propose changes to identity files (SOUL.md, IDENTITY.md, USER.md) based on observed patterns. By default a human reviews and approves or rejects via CLI; optionally you can enable automatic handling so proposals are applied without human review.

Overview

When persona proposals are enabled, the agent gets two tools:

persona_propose — Submit a proposed change to an identity file (title, observation, suggested text, confidence, evidence sessions).
persona_proposals_list — List proposals filtered by status or target file.

Proposals are stored in a separate SQLite database (proposals.db next to facts.db). Human-only CLI commands can approve, reject, or apply proposals:

openclaw proposals review <id> <approve|reject>
openclaw proposals apply <id> — Writes the suggested change into the target file (only for proposals that are already approved).

If personaProposals.autoApply is enabled, proposals that pass validation are approved and applied automatically (no human review). See Automatic handling (opt-in) below.

Safety is enforced by: allowed-file allowlist, rate limit (e.g. 5/week), minimum confidence and evidence, optional expiry, and a full audit trail.

Enabling

Add to the plugin config in openclaw.json:

{
  "personaProposals": {
    "enabled": true
  }
}

To allow the agent to apply proposals without human review, set autoApply: true (see Automatic handling (opt-in)). All other options are optional and have defaults (see Configuration below).

Agent tools

persona_propose

Proposes a change to one of the allowed identity files.

Parameter	Type	Description
`targetFile`	enum	One of `SOUL.md`, `IDENTITY.md`, `USER.md` (or subset if you restrict `allowedFiles`).
`title`	string	Short title (e.g. “Add tone-matching guidance”).
`observation`	string	What the agent observed that motivates the change.
`suggestedChange`	string	The exact text to add/change in the file.
`confidence`	number	0–1; must be ≥ `minConfidence` (default 0.7).
`evidenceSessions`	string[]	Session IDs or references supporting the proposal; length must be ≥ `minSessionEvidence` (default 10).

Checks before creating:

Rate limit: proposals created in the last 7 days must be < maxProposalsPerWeek (default 5).
Confidence ≥ minConfidence.
evidenceSessions.length ≥ minSessionEvidence.

On success, the proposal is stored with status pending and an expiry (if proposalTTLDays > 0). If autoApply is enabled, the proposal is then approved and applied immediately; otherwise the agent is told the proposal ID and that it awaits human review.

Triage pending proposals

openclaw hybrid-mem proposals triage classifies pending persona proposals through the shared pending-autopilot safety contract.

openclaw hybrid-mem proposals triage --dry-run --policy report-only --json
openclaw hybrid-mem proposals triage --apply --policy cautious --max 20
openclaw hybrid-mem proposals triage --apply --policy apply-safe --max 20

Policies:

report-only (default): classify and bundle only; no proposal state, target file, or durable autopilot state mutation.
cautious: may auto-reject high-confidence duplicates, stale/noisy/non-actionable, or low-confidence proposals; semantic persona/user/security/privacy changes are deferred.
apply-safe: may apply only tiny, low-risk, localized, evidence-backed changes after lock/CAS revalidation. Sensitive persona files (SOUL.md, USER.md, IDENTITY.md, AGENTS.md, and sensitive TOOLS.md) require human review for semantic writes.

Proposal text is untrusted input. Prompt-injection content is classified as security risk, target paths are canonicalized under the workspace allowlist, and JSON/audit/bundle output is redacted so secrets/private data are not persisted.

persona_proposals_list

Lists proposals with optional filters:

status — pending approved rejected applied
targetFile — filter by file

Returns id, status, title, target file, confidence, evidence count, created/expires. No file contents; use review/apply on the CLI to see or apply the change.

Human-only CLI

These commands are not exposed as agent tools. Only a human (or a process you control) should run them.

Review (approve or reject)

openclaw proposals review <proposalId> approve
openclaw proposals review <proposalId> reject

Optional: --reviewed-by "name" to record who reviewed.

Only proposals with status pending can be reviewed.
After approve, the proposal status becomes approved; you can then run openclaw proposals apply <proposalId>.
After reject, the proposal is closed; it cannot be applied.

Apply (write to file)

openclaw proposals apply <proposalId>

Only proposals with status approved can be applied.
The target file must still be in allowedFiles.
Path traversal is blocked (no .., /, \ in targetFile).
The plugin resolves the path via api.resolvePath(proposal.targetFile) and appends the suggested change in a comment block plus the new content. Then the proposal is marked applied.

If the target file is missing or write fails, an error is printed and the proposal remains approved so you can fix the path and try again.

Configuration

Option	Default	Description
`enabled`	`false`	Turn persona proposals on.
`autoApply`	`false`	When `true`, proposals that pass validation are approved and applied automatically (no human review). Use with care: the agent can modify identity files.
`allowedFiles`	`["SOUL.md", "IDENTITY.md", "USER.md"]`	Only these identity files can be modified by proposals.
`maxProposalsPerWeek`	`5`	Rate limit: max new proposals in a rolling 7-day window.
`minConfidence`	`0.7`	Minimum confidence (0–1) for the agent to submit a proposal.
`proposalTTLDays`	`30`	Days until a pending proposal expires; expired ones are pruned. Use `0` for no expiry.
`minSessionEvidence`	`10`	Minimum number of session references required in `evidenceSessions`.
`requireScopeFilter`	`false`	When `true`, `generate-proposals` throws an error (instead of logging a warning) if `autoRecall.scopeFilter` is not set and the store contains non-global scoped facts. Recommended for multi-agent/multi-user hosts.

See CONFIGURATION.md for where to put these in openclaw.json.

Multi-agent / multi-user hosts

When multiple agents or users share the same memory store, proposal generation can inadvertently include facts belonging to other agents or users if autoRecall.scopeFilter is not set. This is because generate-proposals reads all active pattern and rule facts without scope restriction.

Recommended configuration for shared-memory deployments:

{
  "autoRecall": {
    "scopeFilter": { "agentId": "my-agent", "userId": "alice" }
  },
  "personaProposals": {
    "enabled": true,
    "requireScopeFilter": true
  }
}

Set autoRecall.scopeFilter to restrict proposal inputs to facts belonging to the correct agent/user.
Set personaProposals.requireScopeFilter: true to hard-fail generate-proposals instead of only warning when the scope filter is absent — this prevents silent cross-scope contamination in production.

Audit health will warn when personaProposals.enabled is true but autoRecall.scopeFilter is not configured, so you can catch this misconfiguration during regular health checks.

Single-user installs (all facts are global scope) are not affected because the warning and hard-fail only trigger when the store contains non-global scoped facts.

Automatic handling (opt-in)

Set personaProposals.autoApply: true to allow the agent to apply proposals to identity files without human review. When a proposal is created and passes all checks (rate limit, confidence, evidence), it is immediately marked approved and written to the target file (with backup and audit log).

When to use: Useful for fully autonomous agents or dev environments where you trust the agent to evolve SOUL.md, IDENTITY.md, or USER.md. Rate limits, min confidence, and min evidence still apply.

Risks: The agent can append or (with high-enough confidence) replace content in identity files. Only enable if you are comfortable with automatic changes. You can still inspect the audit trail under the memory directory (decisions/proposal-<id>.jsonl) and use backups (.backup-<timestamp>) if something goes wrong.

Safety and behaviour

No auto-apply by default. Identity files are only changed when a human runs openclaw proposals apply, or when autoApply is enabled (proposals are then applied immediately after creation).
Allowlist. Only filenames in allowedFiles are accepted; path traversal in targetFile is rejected.
Rate limit. persona_propose fails when the 7-day proposal count would exceed maxProposalsPerWeek.
Evidence and confidence. Proposals below minConfidence or with fewer than minSessionEvidence references are rejected.
Expiry. Pending proposals older than proposalTTLDays are removed by a daily prune (every 24 hours when the gateway is running). They cannot be reviewed or applied after expiry.
Audit. Each create/review/apply is logged to an audit file under the memory directory (e.g. proposal-<id>.jsonl) for traceability.

Background job

When persona proposals are enabled, a timer runs daily (every 24 hours) and deletes pending proposals whose expires_at is in the past. Log message: memory-hybrid: pruned N expired proposal(s).

CONFIGURATION.md — Full config reference
ARCHITECTURE.md — Role of SOUL.md, IDENTITY.md, USER.md
FEATURES.md — Other plugin features