Memory Management API — Save, Recall, Forget, and Export

Use these endpoints to directly manage the memory store — save insights explicitly, list stored memories, delete outdated entries, and import or export your full memory database for backup or migration. These endpoints give you precise control over what Agent Memory retains, independent of the automatic hook-capture pipeline.

POST /agentmemory/remember

Saves an observation or insight to long-term memory. Use this to explicitly capture decisions, patterns, or facts that you want available in future sessions — even if no session hook fired. Returns 201 Created on success.

Request

curl -X POST http://localhost:3111/agentmemory/remember \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The auth service uses JWT tokens with 24-hour expiry, refresh tokens rotate on each use with a 7-day sliding window.",
    "type": "architecture",
    "project": "my-project",
    "concepts": ["auth", "JWT", "refresh-token"],
    "files": ["src/auth/tokens.ts", "src/middleware/auth.ts"],
    "ttlDays": 90
  }'

content

string

required

The memory content to save. Be specific — Agent Memory uses this text for BM25 keyword indexing and vector embedding, so precise wording improves future recall accuracy.

type

string

Memory classification. One of:

pattern — a recurring code pattern or approach
preference — a developer or team preference
architecture — an architectural decision
bug — a known bug or gotcha
workflow — a workflow or process step
fact — a general factual statement

Defaults to fact if not supplied.

project

string

Project name to scope this memory. If set, the memory is included in project-scoped recalls and profile queries.

concepts

string[]

Concept tags used to improve retrieval. These are indexed separately from the content and used by the BM25 and graph search streams.

files

string[]

Related file paths. Used by the enrichment and file-context endpoints to surface this memory when the agent opens these files.

ttlDays

number

Number of days after which this memory should begin to decay. Agent Memory will set a forgetAfter timestamp and evict the memory during the next decay sweep.

sourceObservationIds

string[]

IDs of observations that this memory was derived from. Provides provenance — you can trace any memory back to the raw session event.

Response

{
  "memoryId": "mem_xyz789",
  "strength": 1.0,
  "version": 1,
  "isLatest": true
}

memoryId

string

Unique identifier for the saved memory. Use this to retrieve, evolve, or delete the memory later.

strength

number

Initial memory strength between 0.0 and 1.0. Strength increases each time the memory is recalled and decays over time via the Ebbinghaus curve.

POST /agentmemory/forget

Deletes observations or memories. You can delete by memoryId (removes a specific long-term memory) or by sessionId (removes all observations for a session).

Forget operations are logged in the audit trail but are not reversible unless you have a snapshot created with POST /agentmemory/snapshot/create beforehand.

Delete a specific memory

curl -X POST http://localhost:3111/agentmemory/forget \
  -H "Content-Type: application/json" \
  -d '{ "memoryId": "mem_xyz789" }'

Delete all observations for a session

curl -X POST http://localhost:3111/agentmemory/forget \
  -H "Content-Type: application/json" \
  -d '{ "sessionId": "sess_abc123" }'

You can also pass both sessionId and observationIds together to delete specific observations within a session:

{
  "sessionId": "sess_abc123",
  "observationIds": ["obs_1", "obs_2"]
}

memoryId

string

ID of a long-term memory to delete. Required unless sessionId is provided.

sessionId

string

Session ID to clear. Removes all observations for the session. Required unless memoryId is provided.

observationIds

string[]

Specific observation IDs to delete within the given sessionId. If omitted, all observations for the session are removed.

GET /agentmemory/memories

Lists stored long-term memories with optional filtering and pagination. For large corpora, use limit and offset to page through results.

# Count only (no payload — fastest for dashboards)
curl "http://localhost:3111/agentmemory/memories?count=true"

# Paginated list
curl "http://localhost:3111/agentmemory/memories?limit=50&offset=0&latest=true"

Query param	Type	Description
`count`	boolean	Return only `{ total, latestCount }` — no memory payload. Useful for status checks.
`latest`	boolean	When `true`, return only the most recent version of each memory (`isLatest=true`).
`limit`	number	Max memories to return (capped at 5000).
`offset`	number	Pagination offset (default `0`).
`agentId`	string	Filter by agent ID. Pass `*` to bypass scope isolation.
`includeOrphans`	boolean	When `true`, also return memories with no `agentId` (created before agent scoping was enabled).

Response

{
  "memories": [
    {
      "id": "mem_xyz789",
      "title": "JWT refresh token rotation",
      "content": "Auth uses JWT with 24-hour expiry; refresh tokens rotate on use.",
      "type": "architecture",
      "concepts": ["auth", "JWT", "refresh-token"],
      "files": ["src/auth/tokens.ts"],
      "strength": 0.91,
      "version": 2,
      "isLatest": true,
      "project": "my-project",
      "createdAt": "2025-01-10T09:00:00.000Z",
      "updatedAt": "2025-01-15T11:00:00.000Z"
    }
  ],
  "total": 847,
  "offset": 0,
  "limit": 50
}

GET /agentmemory/memories/:id

Retrieves a single memory by its ID.

curl http://localhost:3111/agentmemory/memories/mem_xyz789

Returns { "memory": Memory } or 404 if the memory does not exist.

GET /agentmemory/profile

Returns the memory profile for a project — the top concepts, most-accessed files, learned conventions, and common error patterns that Agent Memory has built up across all sessions for this project.

curl "http://localhost:3111/agentmemory/profile?project=my-project"

project

string

required

The project name to retrieve the profile for. Returns 400 if omitted.

Response

{
  "project": "my-project",
  "updatedAt": "2025-01-15T11:00:00.000Z",
  "topConcepts": [
    { "concept": "auth", "frequency": 34 },
    { "concept": "database", "frequency": 21 },
    { "concept": "api", "frequency": 18 }
  ],
  "topFiles": [
    { "file": "src/auth/tokens.ts", "frequency": 19 },
    { "file": "src/db/index.ts", "frequency": 12 }
  ],
  "conventions": [
    "Uses TypeScript strict mode",
    "Postgres with Drizzle ORM",
    "JWT via jose (not jsonwebtoken) for Edge compatibility"
  ],
  "commonErrors": [
    "N+1 queries when fetching user relations"
  ],
  "recentActivity": [
    "Implemented refresh token rotation",
    "Added rate limiting middleware"
  ],
  "sessionCount": 42,
  "totalObservations": 1834,
  "summary": "A TypeScript API with JWT auth, Postgres, and Drizzle ORM."
}

POST /agentmemory/evolve

Updates an existing memory with new content while preserving its version history. Use this when you learn that a previous memory was incorrect or incomplete. The old version is retained and marked as superseded.

curl -X POST http://localhost:3111/agentmemory/evolve \
  -H "Content-Type: application/json" \
  -d '{
    "memoryId": "mem_xyz789",
    "newContent": "JWT tokens now use 1-hour expiry (changed from 24h). Refresh tokens still rotate with a 7-day sliding window.",
    "newTitle": "JWT token expiry updated to 1 hour"
  }'

memoryId

string

required

ID of the memory to evolve.

newContent

string

required

The updated memory content. The previous version is stored and linked as a supersedes relation.

newTitle

string

Optional new title for the evolved memory.

GET /agentmemory/export

Exports all memory data as a single JSON object. Use this to back up your memory store, migrate to a new machine, or inspect raw state.

curl "http://localhost:3111/agentmemory/export" > agentmemory-backup.json

For large corpora, paginate using maxSessions and offset:

# Export 50 sessions at a time
curl "http://localhost:3111/agentmemory/export?maxSessions=50&offset=0"
curl "http://localhost:3111/agentmemory/export?maxSessions=50&offset=50"

Query param	Type	Description
`maxSessions`	number	Max sessions to include per page.
`offset`	number	Session offset for pagination (default `0`).

Response

The response is an ExportData object containing:

{
  "version": "0.9.27",
  "exportedAt": "2025-01-15T12:00:00.000Z",
  "sessions": [...],
  "observations": { "sess_abc123": [...] },
  "memories": [...],
  "summaries": [...],
  "profiles": [...],
  "graphNodes": [...],
  "graphEdges": [...],
  "semanticMemories": [...],
  "proceduralMemories": [...],
  "lessons": [...],
  "insights": [...],
  "pagination": {
    "offset": 0,
    "limit": 50,
    "total": 312,
    "hasMore": true
  }
}

POST /agentmemory/import

Imports memory data from a previous export. Wrap the ExportData object in an exportData field:

curl -X POST http://localhost:3111/agentmemory/import \
  -H "Content-Type: application/json" \
  -d '{
    "exportData": { ... },
    "strategy": "merge"
  }'

exportData

object

required

An ExportData object from a previous GET /agentmemory/export call.

strategy

string

Import conflict strategy. One of:

merge (default) — combine imported data with existing data
replace — replace existing data with the import
skip — skip any records that already exist

GET /agentmemory/audit

Returns the full audit trail of memory operations — every remember, forget, consolidate, evolve, import, export, and governance operation, with timestamps, function IDs, target memory IDs, and agent IDs.

curl "http://localhost:3111/agentmemory/audit?limit=50&operation=remember"

Query param	Type	Description
`limit`	number	Max audit entries to return (default `50`).
`operation`	string	Filter by operation type (e.g. `remember`, `forget`, `consolidate`, `import`, `export`).

Response

{
  "entries": [
    {
      "id": "audit_001",
      "timestamp": "2025-01-15T11:00:00.000Z",
      "operation": "remember",
      "functionId": "mem::remember",
      "targetIds": ["mem_xyz789"],
      "details": { "project": "my-project", "type": "architecture" },
      "qualityScore": 0.88
    }
  ],
  "success": true
}

Use the audit trail before bulk-deleting memories via POST /agentmemory/governance/bulk-delete. The operation filter lets you review what Agent Memory has been doing automatically on your behalf.

Governance Endpoints

DELETE /agentmemory/governance/memories

Bulk-deletes specific memories by ID with a mandatory audit log entry.

curl -X DELETE http://localhost:3111/agentmemory/governance/memories \
  -H "Content-Type: application/json" \
  -d '{
    "memoryIds": ["mem_abc", "mem_def"],
    "reason": "Outdated after auth system rewrite"
  }'

POST /agentmemory/governance/bulk-delete

Bulk-deletes memories matching a filter. Supports dryRun=true to preview what would be deleted.

curl -X POST http://localhost:3111/agentmemory/governance/bulk-delete \
  -H "Content-Type: application/json" \
  -d '{
    "type": ["bug"],
    "dateTo": "2024-06-01T00:00:00.000Z",
    "qualityBelow": 0.3,
    "dryRun": true
  }'

Field	Type	Description
`type`	string[]	Memory types to delete.
`dateFrom`	string	ISO date — only delete memories created after this date.
`dateTo`	string	ISO date — only delete memories created before this date.
`qualityBelow`	number	Delete memories with a quality score below this threshold.
`dryRun`	boolean	When `true`, returns what would be deleted without actually deleting.

Memory Consolidation

POST /agentmemory/consolidate

Manually triggers the 4-tier memory consolidation pipeline. Requires CONSOLIDATION_ENABLED=true and a configured LLM provider.

curl -X POST http://localhost:3111/agentmemory/consolidate \
  -H "Content-Type: application/json" \
  -d '{ "project": "my-project", "minObservations": 10 }'

Returns 503 with { "flag": "CONSOLIDATION_ENABLED", "enableHow": "..." } if consolidation is not enabled.

POST /agentmemory/consolidate-pipeline

Runs a specific consolidation tier. Accepts an optional tier field ("working", "episodic", "semantic", "procedural").

POST /agentmemory/evict

Evicts memories that have decayed below the retention threshold. Supports ?dryRun=true to preview evictions.

curl -X POST "http://localhost:3111/agentmemory/evict?dryRun=true"

​POST /agentmemory/remember

​Request

​Response

​POST /agentmemory/forget

​Delete a specific memory

​Delete all observations for a session

​GET /agentmemory/memories

​Response

​GET /agentmemory/memories/:id

​GET /agentmemory/profile

​Response

​POST /agentmemory/evolve

​GET /agentmemory/export

​Response

​POST /agentmemory/import

​GET /agentmemory/audit

​Response

​Governance Endpoints

​DELETE /agentmemory/governance/memories

​POST /agentmemory/governance/bulk-delete

​Memory Consolidation

​POST /agentmemory/consolidate

​POST /agentmemory/consolidate-pipeline

​POST /agentmemory/evict

POST /agentmemory/remember

Request

Response

POST /agentmemory/forget

Delete a specific memory

Delete all observations for a session

GET /agentmemory/memories

Response

GET /agentmemory/memories/:id

GET /agentmemory/profile

Response

POST /agentmemory/evolve

GET /agentmemory/export

Response

POST /agentmemory/import

GET /agentmemory/audit

Response

Governance Endpoints

DELETE /agentmemory/governance/memories

POST /agentmemory/governance/bulk-delete

Memory Consolidation

POST /agentmemory/consolidate

POST /agentmemory/consolidate-pipeline

POST /agentmemory/evict