What are memory stores?

A memory store is a named, project-level container for memories. You create a store, attach it to one or more agents, and those agents can read from and write to it. Memories persist across sessions and conversations.

There are two modes:

• Shared stores — every agent with access sees the same pool of memories. Good for team knowledge, company facts, and product context.
• User-scoped stores — each end-user gets their own isolated partition within the store. Agent A talking to User 1 sees only User 1's memories. Good for personalization, preferences, and anything subject to data privacy requirements.

You choose the mode when you create the store.

Why two modes?

Shared stores are the simple case. Your support agent accumulates product knowledge, and every agent on the project benefits.

User-scoped stores exist because of a harder problem: your users are not your agents. When User A tells your agent they're vegetarian, User B shouldn't see that. When User A requests deletion of their data, you need to delete their memories without touching anyone else's.

This matters for:

• GDPR and data subject rights — user-scoped stores give each user an isolated memory partition. Deleting a user's data is a targeted operation, not a full-store wipe.
• Multi-tenant applications — if your agents serve different customers, user scoping prevents data leakage between them.
• Personalization — preferences, history, and context stay with the user they belong to.

Shared stores skip this overhead when you don't need it. Use them for organizational knowledge that applies to everyone.

Quick start

1. Create a memory store

# Shared store — all agents see the same memories
curl -X POST https://api.ragwalla.com/memory_stores \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Knowledge",
    "description": "Shared facts about our product catalog",
    "embedding_model": "text-embedding-3-small"
  }'

{
  "id": "ms_abc123",
  "object": "memory_store",
  "project_id": "proj_xyz",
  "name": "Product Knowledge",
  "description": "Shared facts about our product catalog",
  "embedding_model": "text-embedding-3-small",
  "user_scoping_enabled": false,
  "created_at": 1710000000,
  "updated_at": 1710000000
}

For a user-scoped store, set user_scoping_enabled:

# User-scoped store — each user_id gets an isolated memory partition
curl -X POST https://api.ragwalla.com/memory_stores \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "User Preferences",
    "embedding_model": "text-embedding-3-small",
    "user_scoping_enabled": true
  }'

2. Attach the store to an agent

curl -X POST https://api.ragwalla.com/agents/ag_myagent/memory_stores \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_store_id": "ms_abc123",
    "role": "read_write",
    "is_default": true
  }'

{
  "agent_id": "ag_myagent",
  "memory_store_id": "ms_abc123",
  "store_name": "Product Knowledge",
  "role": "read_write",
  "is_default": true,
  "embedding_model": "text-embedding-3-small",
  "user_scoping_enabled": false
}

Setting is_default: true means this store is used automatically during conversation — the agent's memory extraction pipeline writes to it without any explicit targeting.

3. Write memories

curl -X POST https://api.ragwalla.com/agents/ag_myagent/memories \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The enterprise plan includes SSO and audit logs",
    "memory_store_id": "ms_abc123",
    "memory_type": "fact",
    "importance": 0.9,
    "tags": ["pricing", "enterprise"]
  }'

For user-scoped stores, include user_id:

curl -X POST https://api.ragwalla.com/agents/ag_myagent/memories \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Prefers dark mode and compact layout",
    "memory_store_id": "ms_userprefs",
    "memory_type": "preference",
    "user_id": "user_42"
  }'

4. Search memories

curl -X POST https://api.ragwalla.com/agents/ag_myagent/memories/search \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what plan has SSO?",
    "memory_store_id": "ms_abc123",
    "top_k": 5
  }'

{
  "object": "list",
  "data": [
    {
      "id": "mem_xyz789",
      "object": "memory",
      "content": "The enterprise plan includes SSO and audit logs",
      "memory_type": "fact",
      "importance": 0.9,
      "tags": ["pricing", "enterprise"],
      "score": 0.94,
      "created_at": 1710000000
    }
  ]
}

For user-scoped stores, add user_id to scope the search:

curl -X POST https://api.ragwalla.com/agents/ag_myagent/memories/search \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "UI preferences",
    "memory_store_id": "ms_userprefs",
    "user_id": "user_42",
    "top_k": 3
  }'

This returns only User 42's memories. No other user's data is visible.

5. List memories

# List all memories in a shared store
curl "https://api.ragwalla.com/agents/ag_myagent/memories?memory_store_id=ms_abc123&limit=20"

# List a specific user's memories in a user-scoped store
curl "https://api.ragwalla.com/agents/ag_myagent/memories?memory_store_id=ms_userprefs&user_id=user_42&limit=20"

Sharing a store across agents

A single store can be attached to multiple agents. Each attachment has its own role.

# Agent A: full access
curl -X POST https://api.ragwalla.com/agents/ag_support/memory_stores \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "memory_store_id": "ms_abc123", "role": "read_write" }'

# Agent B: read-only access
curl -X POST https://api.ragwalla.com/agents/ag_sales/memory_stores \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "memory_store_id": "ms_abc123", "role": "read" }'

Agent B can search and retrieve memories but cannot create or delete them. This is useful when one agent curates knowledge and others consume it.

Automatic memory extraction

When an agent has a default memory store and memory extraction is enabled, the agent automatically extracts memories from conversations and writes them to the store. No manual POST /memories calls needed — the agent learns from every conversation.

For user-scoped default stores, extracted memories are automatically partitioned by the conversation's user_id.

Access control

Every store operation requires the agent to have an explicit attachment with the correct role:

Attempting a write with read access returns 403. Attempting any operation on an unattached store returns 403.

Managing stores

List all stores in a project

curl "https://api.ragwalla.com/memory_stores?limit=20&offset=0" \
  -H "Authorization: Bearer $API_KEY"

Update a store

curl -X PUT https://api.ragwalla.com/memory_stores/ms_abc123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Knowledge Base",
    "description": "Updated description"
  }'

name, description, and user_scoping_enabled can be updated after creation. The embedding_model is immutable — it is set once at creation and cannot be changed, because existing memories were vectorized with that model.

List an agent's attached stores

curl https://api.ragwalla.com/agents/ag_myagent/memory_stores \
  -H "Authorization: Bearer $API_KEY"

{
  "object": "list",
  "data": [
    {
      "agent_id": "ag_myagent",
      "memory_store_id": "ms_abc123",
      "store_name": "Product Knowledge",
      "role": "read_write",
      "is_default": true,
      "embedding_model": "text-embedding-3-small",
      "user_scoping_enabled": false
    }
  ]
}

Detach a store from an agent

curl -X DELETE https://api.ragwalla.com/agents/ag_myagent/memory_stores/ms_abc123 \
  -H "Authorization: Bearer $API_KEY"

Delete a store

curl -X DELETE https://api.ragwalla.com/memory_stores/ms_abc123 \
  -H "Authorization: Bearer $API_KEY"

A store cannot be deleted while agents are still attached. Detach all agents first, or the API returns 409 Conflict:

{
  "error": "Cannot delete memory store: 2 agent(s) still attached"
}

Deleting a store permanently removes all associated memories, vector indexes, and infrastructure.

Use cases

Team knowledge base (shared store)

A support team has multiple specialized agents — billing, technical, onboarding. All share a single "Company Knowledge" store. When the billing agent learns that pricing changed, the technical agent can reference it in the next conversation.

# Create the shared store
curl -X POST https://api.ragwalla.com/memory_stores \
  -H "Authorization: Bearer $API_KEY" \
  -d '{ "name": "Company Knowledge", "embedding_model": "text-embedding-3-small" }'

# Attach to all three agents with read_write
for agent in ag_billing ag_technical ag_onboarding; do
  curl -X POST "https://api.ragwalla.com/agents/$agent/memory_stores" \
    -H "Authorization: Bearer $API_KEY" \
    -d "{ \"memory_store_id\": \"ms_companyknowledge\", \"role\": \"read_write\", \"is_default\": true }"
done

Per-user personalization (user-scoped store)

A fitness coaching agent remembers each user's goals, injuries, and preferences. User A's knee injury doesn't show up in User B's workout plan.

# Create the user-scoped store
curl -X POST https://api.ragwalla.com/memory_stores \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "name": "User Health Profiles",
    "embedding_model": "text-embedding-3-small",
    "user_scoping_enabled": true
  }'

When User A asks to delete their data, you delete their memories without affecting anyone else:

# List User A's memories
curl "https://api.ragwalla.com/agents/ag_coach/memories?memory_store_id=ms_health&user_id=user_A"

# Delete them individually
curl -X DELETE "https://api.ragwalla.com/agents/ag_coach/memories/mem_123?memory_store_id=ms_health&user_id=user_A"

Curator + consumer pattern (mixed roles)

One agent writes, others read. A research agent ingests and curates market intelligence. Sales agents consume it but can't modify it.

# Research agent: read_write
curl -X POST https://api.ragwalla.com/agents/ag_research/memory_stores \
  -H "Authorization: Bearer $API_KEY" \
  -d '{ "memory_store_id": "ms_market", "role": "read_write", "is_default": true }'

# Sales agents: read-only
curl -X POST https://api.ragwalla.com/agents/ag_sales_east/memory_stores \
  -H "Authorization: Bearer $API_KEY" \
  -d '{ "memory_store_id": "ms_market", "role": "read" }'

Memory types

When creating memories, you can classify them:

Memory types are optional metadata — they help with filtering but don't change how memories are stored or retrieved.

API reference summary

All memory endpoints accept optional memory_store_id and user_id parameters to target a specific store and user partition.