How AIClaw Adds Durable Memory Without Turning Prompt Context Into a Global Text File

AI agents need memory, but most "memory" implementations are either too weak to be useful or too loose to be safe. A flat MEMORY.md file is simple, but it quickly becomes hard to audit, hard to scope, and easy to over-inject into prompts.

AIClaw's latest memory work takes a different approach: memory is now stored as application data with ownership, scope, review status, search, evidence, and UI controls. The goal is not to make the model blindly obey old notes. The goal is to give an agent durable context that stays inspectable and bounded.

The problem with file-style memory

The old mental model for agent memory is straightforward: save some useful facts, load them into the next run, and hope the assistant gets better over time.

That breaks down in real use:

• Not every remembered fact should apply to every agent.
• User-specific context should not leak across users.
• Candidate notes should not be injected as if they were trusted truth.
• Sensitive content needs review before it becomes active context.
• Operators need to know what memory was used in a given answer.

AIClaw now treats memory as structured state instead of a shared free-form prompt file.

What changed in AIClaw

The new Durable Memory section in the README describes a database-backed Memory System where each memory record carries:

• an owner
• a scope
• a kind
• a stable key
• importance and confidence
• status
• revision history
• evidence links

Two scopes define visibility:

• user: available to every agent for the same user
• agent_user: available only to one user and one specific agent

That is a practical design choice. Some facts are general preferences like response style. Others are agent-specific procedures that should stay bound to one agent.

Memory is reviewable, not magical

One of the most useful parts of this design is the lifecycle:

candidate -> active -> superseded / dismissed / deleted

This means agent-written memory does not have to become active prompt context immediately.

In the new service layer, propose writes candidate memory, while upsert can create active memory. Sensitive writes are forced back to candidate status even if something tries to mark them active. That gives operators a real review boundary instead of a best-effort convention.

The new web Memory page exposes that workflow directly. You can:

• browse active memories
• inspect candidates separately
• search and filter by scope and kind
• approve or dismiss candidates
• edit, pin, expire, or delete records
• inspect revision history and evidence

That is much closer to how teams actually need agent memory to work.

Retrieval is scoped before it reaches the prompt

The most important runtime behavior is not storage. It is retrieval.

According to docs/design/memory-system.md, AIClaw retrieves only:

1. active, unexpired records
2. for the current user
3. for the current agent when scope is agent_user

Candidate records, foreign-user records, and other-agent records are excluded from prompt injection.

The memory service then adds pinned records, de-duplicates the set, compacts it to a prompt budget, and renders a bounded <memory_context> block with a safety preamble: retained memory is context, not instruction, and it loses to the current user request and verified tool results.

That distinction matters. A lot of memory systems fail because old notes become pseudo-system prompts. AIClaw is explicitly avoiding that.

Evidence and auditability are first-class

Another strong design choice is the evidence model.

Each memory can accumulate:

• source evidence showing where it came from
• usage evidence linking it to a run and final assistant message

So when a memory influences an answer, there is a trail. The README and design doc both emphasize that the final memory snapshot can be shown beside chat and execution logs without mixing memory content into the assistant response body itself.

This is the kind of detail that makes durable memory operationally useful instead of just conceptually interesting.

The tests cover the failure modes you actually worry about

The new memory tests are worth reading because they target the right risks.

TestBuildContextIsolatedAndCandidateSafe verifies that:

• only the current user's records are retrieved
• agent-specific memory does not leak from another agent
• candidate memory is excluded
• the prompt includes the safety boundary text

TestSensitiveMemoryRequiresReview verifies that sensitive memory cannot stay active and is pushed back to candidate review status.

TestToolProposalCreatesCandidate verifies that tool-driven proposals create candidate memories rather than silently activating them.

Those are the right invariants for a production memory feature.

What this looks like in practice

Here is a realistic workflow:

1. A user repeatedly asks one agent for terse release notes and detailed test evidence.
2. The agent proposes that as an agent_user preference.
3. The operator reviews it in the Memory page and approves it.
4. Future runs for that same user-agent pair can retrieve it automatically.
5. Another agent for the same user does not inherit that preference unless the scope is intentionally broader.

This keeps memory useful without making it global by accident.

Why I picked this feature for today's article

This is a concrete new feature from the July 19, 2026 commit feat(memory): add scoped durable memory system. It also fills a different slot than the earlier AIClaw article about memory/session search: that earlier topic focused on finding prior conversations, while this one is about durable, scoped, reviewable context that can be injected into future runs.

For AI agent systems, memory is one of the easiest places to be vague. AIClaw's newer implementation is specific about scope, review, retrieval, and evidence. That makes it worth documenting on its own.