> ## Documentation Index
> Fetch the complete documentation index at: https://docs.herm.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory and self-learning

> Understand subject-scoped memory, session recall, and learned skills.

Herm carries useful context across sessions without requiring your application
to replay every prior turn. Memory is scoped to the organization, agent, and
stable `subjectId` supplied when a session is created.

## Memory

The built-in `memory` tool lets the agent save, replace, and remove durable
facts. `session_search` lets it retrieve relevant context from previous
conversations. Both toolsets can be configured through the agent's `tools`
array.

Each subject has two managed memory stores:

| Store        | Runtime file | Purpose                                                                                                                        |
| ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| User memory  | `USER.md`    | The user's identity, preferences, communication style, habits, and stable personal context.                                    |
| Agent memory | `MEMORY.md`  | Environment facts, project conventions, tool quirks, and durable lessons the agent has learned while working for that subject. |

The stores are scoped to the organization, agent, and `subjectId`. Herm manages
their persistence and makes them available across the subject's sessions. Do not
write `memories/USER.md` or `memories/MEMORY.md` through the
[Files API](/api-reference/files); those paths are reserved for this memory
surface.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "agent_toolset",
  "configs": [
    { "name": "memory", "enabled": true },
    { "name": "session_search", "enabled": true }
  ]
}
```

Reuse the same `subjectId` for the same person, team, organization, or workspace.
Changing it intentionally creates a separate memory and workspace boundary.

## Seed memory before the first session

You can initialize both stores before creating a subject's first session. This
is useful when your application already knows customer preferences, account
context, project conventions, or environment details that the agent should have
on its first turn.

Treat seeding as trusted agent configuration. Seed concise, operator-authored
facts; do not forward raw end-user messages or untrusted documents into this
endpoint.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request PUT \
  https://api.herm.run/v1/agents/$AGENT_ID/users/$SUBJECT_ID/memory \
  --header "x-api-key: $HERM_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "userMemoryEntries": [
      "Prefers concise responses.",
      "Works in Pacific time."
    ],
    "agentMemoryEntries": [
      "This project uses Bun.",
      "Deployments run through Porter."
    ]
  }'
```

Then create sessions with the same `agentId` and `subjectId`. The seeded entries
are available to the agent on its first turn.

Seeding is intentionally create-only. It returns `409
memory_already_initialized` if memory or prior runtime activity already exists
for the subject. After initialization, Hermes owns ongoing updates through the
memory tool.

User memory is limited to 1,375 characters and agent memory to 2,200 characters.
Keep entries compact and durable. Do not store API keys, passwords, transient
task progress, raw conversation logs, or information that can be cheaply
rediscovered.

## Read memory

Use `GET /v1/memories/:memoryId` to read both stores without starting a session.
The response includes each store's purpose, filename, entries, character usage,
and limit.

## Self-learning

After turns, Hermes periodically reviews work to identify durable facts and
reusable procedures. Useful procedures can become learned skills in the
subject's persistent workspace and can inform later sessions.

Background review is asynchronous and best effort; do not use it as the system
of record for data your application must retain. Put mandatory instructions in
the agent's configured `skills` array instead.

Configured skills are versioned agent configuration. Learned skills are scoped
to an agent and subject and survive across sessions. Public learned-skill
management endpoints are not currently available.

See [Skills](/api-reference/skills) for configured skill behavior and
[Tools](/api-reference/tools#built-in-agent-toolsets) for memory tool controls.