Memory and Context

Memory and projects solve two different forms of continuity.

Memory stores durable facts and preferences that may be useful across conversations. Projects provide a bounded workspace where instructions, files, decisions, conversations, and outputs remain together.

Memory: Lightweight Personalisation

Memory handles facts such as a user's role, stable preferences, recurring context, team conventions, or writing style. It can prevent the user from having to repeat the same information in every conversation.

Memory is not a replacement for source-of-truth data, permissions, or workflow state. A remembered customer tier should not override the CRM, and a remembered approval should not replace an auditable transaction.

Memory tools let an agent store and retrieve appropriate user context across turns and sessions.

# Search memory by semantic query
memory_search(query: string, limit: number): object[]

# List memory entries for an agent/session
memory_list(scope: string, limit: number): object[]

# Store a new memory item
memory_write(scope: string, content: string, metadata: object): string

# Remove a memory item
memory_delete(memory_id: string): string

Example: Save a User Preference

User prompt

Remember it's my birthday on Jan 20th.

1) Model requests a memory write

{
  "role": "assistant",
  "content": "",
  "tool_calls": [
    {
      "id": "call_memory_write_01",
      "name": "memory_write",
      "arguments": "{\"scope\":\"user:42\",\"content\":\"User birthday is Jan 20\",\"metadata\":{\"type\":\"profile\",\"field\":\"birthday\",\"confidence\":\"user_stated\"}}"
    }
  ]
}

2) Dispatcher executes and returns tool result

{
  "role": "tool",
  "name": "memory_write",
  "tool_call_id": "call_memory_write_01",
  "content": "{\"memory_id\":\"mem_01JABCDXYZ\",\"status\":\"stored\"}"
}

3) Model confirms and asks follow-up questions

{
  "role": "assistant",
  "content": "Got it, I will remember your birthday is Jan 20. Do you want me to store the year too? Also, should I remind you a week before each year?"
}

API Call with Full History

Use the full message history when calling the model after tool execution.

curl http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "granite4:tiny-h",
    "stream": false,
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "memory_write",
          "description": "Store a memory item for a user/session scope.",
          "parameters": {
            "type": "object",
            "properties": {
              "scope": { "type": "string" },
              "content": { "type": "string" },
              "metadata": {
                "type": "object",
                "additionalProperties": true
              }
            },
            "required": ["scope", "content"]
          }
        }
      }
    ],
    "messages": [
      {
        "role": "system",
        "content": "You are a careful assistant. Store durable user preferences with tools and ask clarifying questions when fields are ambiguous."
      },
      {
        "role": "user",
        "content": "Remember it'\''s my birthday on Jan 20th."
      },
      {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_memory_write_01",
            "name": "memory_write",
            "arguments": "{\"scope\":\"user:42\",\"content\":\"User birthday is Jan 20\",\"metadata\":{\"type\":\"profile\",\"field\":\"birthday\",\"confidence\":\"user_stated\"}}"
          }
        ]
      },
      {
        "role": "tool",
        "name": "memory_write",
        "tool_call_id": "call_memory_write_01",
        "content": "{\"memory_id\":\"mem_01JABCDXYZ\",\"status\":\"stored\"}"
      }
    ]
  }'

And the result...

Your birthday reminder has been successfully stored! I've saved that it's your birthday on **January 20th**. Let me know if there are any other preferences or details you'd like to add.

Projects: Persistent Workspaces

A project keeps related work together. Its instructions, reference files, prior decisions, and generated outputs establish persistent context for an ongoing body of work.

This is useful for:

• research folders;
• proposal drafting;
• customer analysis;
• compliance reviews;
• report generation;
• code exploration;
• other workflows that continue across conversations.

Before creating a named agent, consider whether a project is the better container. A project preserves the context while allowing the user to perform different kinds of work inside it.

Choose the Right Kind of Context

Context	Use it for
Conversation history	The immediate exchange and current task
Memory	Small, durable facts useful across conversations
Project	Files, instructions, decisions, and outputs for ongoing work
Dataset	Reusable source knowledge that can be searched and cited

Keeping these roles separate reduces accidental data leakage and makes retention, correction, and deletion easier to reason about.

Questions to Ask Before Saving Memory

1. Is this personal data the user actually wants stored?
2. Is the value complete (for example, date without year)?
3. Should this memory expire or stay permanent?
4. Should the assistant create reminder behavior from this memory?

Implementations

• OpenClaw Memory
• Mem0 (Startup)
• IronClaw Source Code in Rust.