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; those paths are reserved for this memory surface.

{
  "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.

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 for configured skill behavior and Tools for memory tool controls.