# Give an agent memory

import { Steps } from "@astrojs/starlight/components"
import Prereqs from "@docs/Prereqs.astro"
import UiWalkthrough from "@docs/UiWalkthrough.astro"
import ClientTabs from "@docs/ClientTabs.astro"

Give an agent persistent memory by creating a memory store and attaching it to a project. Memory stores survive across sessions. The agent can write facts, preferences, and context that carry over from one run to the next.

Small stores are loaded into the agent's context at session start; larger ones are exposed as a retrieval tool the agent queries on demand.

<Prereqs>
  - A Ren account with at least one [project](/docs/deep-dives/concepts/compute/projects/) - [The CLI
  installed](/docs/developers/cli/) and paired, or a personal access token for the API and TypeScript calls
</Prereqs>

## In the UI

<UiWalkthrough>
  {/* TODO(demo): screen recording – creating a memory store from project settings and attaching it, ~8s loop */}
</UiWalkthrough>

<Steps>

1. Navigate to your project's **Settings** tab.

2. Under **Memory stores**, click **Add memory store**.

3. Choose an existing store or create a new one by entering a name.

4. The store is now attached. The next session on this project will have access to it.

</Steps>

## Programmatically

Create a memory store, then attach it to a project. Each project can have multiple memory stores, and each store can be shared across projects.

<ClientTabs clients={["cli", "api", "typescript"]}>
  <Fragment slot="cli">
    <Steps>
      1. Create a memory store:

         ```bash
         ren memory-stores create --name "project-context"
         ```

         The response includes the store `id` (e.g. `mst_abc123`).

      2. Attach it to a project:

         ```bash
         ren projects memory-stores add prj_def456 \
           --memory-store-id mst_abc123
         ```

      3. Upload a file to the store (optional: the agent can also write to it at runtime):

         ```bash
         ren memory-stores files upload mst_abc123 \
           --path "context.md" \
           --file ./context.md
         ```
    </Steps>

    List stores and their files:

    ```bash
    ren memory-stores list
    ren memory-stores files list mst_abc123
    ```

    Detach a store from a project:

    ```bash
    ren projects memory-stores remove prj_def456 mst_abc123
    ```

  </Fragment>
  <Fragment slot="api">
    <Steps>
      1. Create a memory store with `POST /api/memory-stores`:

         ```bash
         curl -X POST https://api.renai.build/api/memory-stores \
           -H "Authorization: Bearer $REN_PAT_TOKEN" \
           -H "Content-Type: application/json" \
           -d '{"name": "project-context"}'
         ```

         The response includes the store `id`.

      2. Attach it to a project with `POST /api/projects/{id}/memory-stores`:

         ```bash
         curl -X POST https://api.renai.build/api/projects/prj_def456/memory-stores \
           -H "Authorization: Bearer $REN_PAT_TOKEN" \
           -H "Content-Type: application/json" \
           -d '{"memoryStoreId": "mst_abc123"}'
         ```

      3. Upload a file to the store (two-step: presign, then PUT):

         ```bash
         # Start the upload
         curl -X POST https://api.renai.build/api/memory-stores/mst_abc123/files/uploads \
           -H "Authorization: Bearer $REN_PAT_TOKEN" \
           -H "Content-Type: application/json" \
           -d '{"path": "context.md", "contentType": "text/markdown"}'

         # PUT the file to the presigned URL returned above, then finalize:
         curl -X POST https://api.renai.build/api/memory-stores/mst_abc123/files/finalize \
           -H "Authorization: Bearer $REN_PAT_TOKEN" \
           -H "Content-Type: application/json" \
           -d '{"path": "context.md"}'
         ```
    </Steps>

  </Fragment>
  <Fragment slot="typescript">
    Create a memory store and attach it to a project:

    ```ts
    import { createRenClient, pat } from "@renai-labs/sdk"

    const client = createRenClient({
      baseUrl: "https://api.renai.build",
      auth: pat(process.env.REN_PAT_TOKEN!),
    })

    const { data: store, error } = await client.memoryStore.create({
      body: { name: "project-context" },
    })
    if (error) throw error
    console.log(store.id) // "mst_abc123"

    await client.project.memoryStore.add({
      path: { id: "prj_def456" },
      body: { memoryStoreId: store.id },
    })
    ```

    Upload files to a store with the CLI (`ren memory-stores files upload`). The
    agent can also write to the store at runtime.

  </Fragment>
</ClientTabs>

Memory stores are scoped to an owner (org or user). One store per owner can be marked `isDefault`. It's automatically attached to new projects in that scope.