AgentOS markAgentOS
Install AgentOS

Memory

AgentOS memory helps the agent recall durable context without replaying every old conversation. Use it for stable preferences, reusable project facts, previous decisions, and notes that should survive across sessions.

Memory is separate from skills. Skills teach the agent how to do a task; memory stores useful facts and context the agent may need later.

What to Store

Good memory entries are stable and reusable:

  • user preferences;
  • project conventions;
  • recurring output formats;
  • names of important repositories, directories, or services;
  • decisions the user wants reused;
  • brief notes from completed tasks.

Avoid memory for:

  • API keys or secrets;
  • raw private data that does not need long-term recall;
  • one-off instructions for the current turn;
  • noisy dumps that would pollute future retrieval;
  • exact transcripts that should instead be exported as session records.

Common Commands

Inspect memory health:

agentos memory status
agentos memory status --deep

Index and list memory sources:

agentos memory index
agentos memory list

Search and inspect memory:

agentos memory search "release note format"
agentos memory show <path>

Search previous sessions as well as memory:

agentos memory search "deployment decision" --source all

Natural Chat Usage

Ask naturally when something should be remembered:

Remember that I prefer concise release notes with a risk section.

Later, refer to the preference:

Use my usual release-note format for this changelog.

When memory seems stale, ask the agent to search explicitly:

Search memory for my release-note preferences before drafting this.

Session-Derived Memory

For long or important sessions, flush session state into memory before archiving, compacting, or switching tasks: 

agentos memory flush-session <session-key>

Use session export when exact old wording matters:

agentos sessions export <session-key>

Memory is for useful recall. Session export is for exact records.

Maintenance and Repair

Refresh the index after editing memory files or changing memory configuration: 

agentos memory index --force

Inspect fallback and repair surfaces:

agentos memory raw-fallbacks list
agentos memory repair list

Show or repair a degraded compaction memory record when instructed by diagnostics: 

agentos memory repair show --summary-id <id>
agentos memory repair run --summary-id <id>

Best Practices

  • Keep entries short and sourceable.
  • Prefer "Remember X for project Y" over vague "remember this."
  • Search memory before assuming the agent forgot.
  • Remove or revise stale preferences instead of adding contradictory ones.
  • Keep secrets out of memory.
  • Use artifacts or files for large reference material.