Data Management & GDPR Compliance

This guide covers how memory data flows through MemoryLayer, how to delete or export it, and how to fulfill GDPR Article 17 (right to erasure) requests using the existing API.

---

Data Lifecycle

Memory data passes through three phases:

1. Creation

Memories are created explicitly via POST /v1/memories, or implicitly when a session is committed (POST /v1/sessions/{session_id}/commit). At creation, each memory receives:

• A unique id (e.g. mem_a1b2c3d4e5f6g7h8)
• A workspace_id scoping it to a tenant boundary
• An importance score (0.0–1.0), defaulting to 0.5
• A status of active
• created_at and updated_at timestamps

2. Access and Decay

Memories are retrieved through POST /v1/memories/recall (vector similarity search) or POST /v1/memories/reflect (LLM synthesis). Between retrievals, importance naturally decays:

• Episodic memories (events, interactions) decay over time
• Semantic memories (facts, preferences) and procedural memories are long-lived
• pinned memories are exempt from decay
• Decay is applied explicitly via POST /v1/memories/{memory_id}/decay

3. Deletion

Memories can be soft-deleted (default) or hard-deleted (permanent). See Deletion below.

---

Deletion

Soft Delete vs Hard Delete

By default, DELETE /v1/memories/{memory_id} performs a soft delete: the memory’s status is set to deleted and deleted_at is recorded. Soft-deleted memories:

• Are excluded from recall and reflect results
• Remain in the database (recoverable by direct storage access)
• Are not returned when include_archived is set to true in recall requests

To permanently remove a memory from storage, pass the hard=true query parameter:

# Soft delete (default) - status set to "deleted", record retained
curl -X DELETE "http://localhost:61001/v1/memories/mem_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Hard delete - record removed from database permanently
curl -X DELETE "http://localhost:61001/v1/memories/mem_abc123?hard=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Both return 204 No Content on success.

Batch Deletion

To delete multiple memories in a single request, use the batch endpoint. Each delete operation in the batch also supports the hard flag:

curl -X POST "http://localhost:61001/v1/memories/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {"op": "delete", "memory_id": "mem_abc123", "hard": true},
      {"op": "delete", "memory_id": "mem_def456", "hard": true},
      {"op": "delete", "memory_id": "mem_ghi789", "hard": false}
    ]
  }'

Response:

{
  "total_operations": 3,
  "successful": 3,
  "failed": 0,
  "results": [
    {"index": 0, "type": "delete", "status": "success", "memory_id": "mem_abc123"},
    {"index": 1, "type": "delete", "status": "success", "memory_id": "mem_def456"},
    {"index": 2, "type": "delete", "status": "success", "memory_id": "mem_ghi789"}
  ]
}

Purging an Entire Workspace

To delete a workspace and all its associated data (memories, sessions, associations), use:

curl -X DELETE "http://localhost:61001/v1/workspaces/ws_yourworkspaceid" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns 204 No Content on success. This is the most complete data removal operation available — it removes the workspace record and all dependent data in a single call.

Deleting a Session

To delete a session and its working memory context:

curl -X DELETE "http://localhost:61001/v1/sessions/sess_yoursessionid" \
  -H "Authorization: Bearer YOUR_API_KEY"

Session deletion removes the session and its working memory entries. Long-term memories previously committed from this session remain in the workspace and must be deleted separately if required.

---

Right to Erasure (GDPR Article 17)

GDPR Article 17 grants data subjects the right to request erasure of their personal data. This section provides a step-by-step procedure to fulfill such a request using the MemoryLayer API.

Caution

The _default workspace cannot be deleted. For GDPR compliance, use per-user workspaces so that all data for a given user is isolated to one workspace ID. See Workspace Isolation.

Step 1: Identify the User’s Workspace

If each user has a dedicated workspace, the workspace ID is the primary handle for their data.

# List all workspaces to find the user's workspace
curl "http://localhost:61001/v1/workspaces" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "workspaces": [
    {"id": "ws_user_alice", "name": "Alice's Workspace", ...},
    {"id": "ws_user_bob",   "name": "Bob's Workspace", ...}
  ]
}

Step 2: Export Data for Audit (Optional but Recommended)

Before deletion, export the user’s data for your compliance records:

curl "http://localhost:61001/v1/workspaces/ws_user_alice/export" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  > alice_data_export.ndjson

See Data Export for full details on the export format.

Step 3: Delete the Workspace

A single workspace deletion removes all memories, sessions, working memory, and associations for that user:

curl -X DELETE "http://localhost:61001/v1/workspaces/ws_user_alice" \
  -H "Authorization: Bearer YOUR_API_KEY"

204 No Content confirms the workspace and all its data have been removed.

Step 4: Verify Deletion

Confirm the workspace no longer exists:

curl "http://localhost:61001/v1/workspaces/ws_user_alice" \
  -H "Authorization: Bearer YOUR_API_KEY"
# Expected: 404 Not Found

Partial Erasure (Selective Memory Deletion)

If a user shares a workspace with other data (not recommended for GDPR use cases), you can recall memories by subject_id and delete them individually:

# 1. Find all memories about a subject
curl -X POST "http://localhost:61001/v1/memories/recall" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "all information",
    "workspace_id": "ws_shared",
    "subject_id": "user_alice",
    "limit": 100
  }'

# 2. Hard-delete each returned memory ID
curl -X DELETE "http://localhost:61001/v1/memories/mem_abc123?hard=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Note

There is currently no bulk-delete-by-subject endpoint. For workloads requiring selective erasure of hundreds of memories, use the batch delete endpoint with the IDs returned from recall, iterating with exclude_ids to page through results.

---

Data Export

The workspace export endpoint streams all memories and associations as NDJSON (newline-delimited JSON), suitable for backup, migration, or GDPR data portability responses.

Export a Workspace

curl "http://localhost:61001/v1/workspaces/ws_yourworkspaceid/export" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  > workspace_export.ndjson

Export Parameters

Parameter	Type	Default	Description
offset	integer	0	Skip first N memories
limit	integer	0	Export at most N memories (0 = all)
include_associations	boolean	true	Include memory relationship graph

# Export first 500 memories only, without associations
curl "http://localhost:61001/v1/workspaces/ws_yourworkspaceid/export?limit=500&include_associations=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

NDJSON Format

Each line is a JSON object with a type field:

{"type":"header","version":"1.0","workspace_id":"ws_abc","exported_at":"2026-04-02T10:00:00Z","total_memories":42,"total_associations":17,"offset":0,"limit":0}
{"type":"memory","index":0,"data":{"id":"mem_abc123","content":"User prefers TypeScript","type":"semantic","importance":0.8,"tags":["language","preference"],"created_at":"2026-01-15T09:30:00Z",...}}
{"type":"memory","index":1,"data":{...}}
{"type":"association","data":{"source_id":"mem_abc123","target_id":"mem_def456","relationship_type":"SIMILAR_TO","strength":0.75,"metadata":{}}}
{"type":"footer","memories_exported":42,"associations_exported":17}

Line types:

• header — Export metadata and counts
• memory — A single memory record with all fields
• association — A directed relationship between two memories
• footer — Final counts summary

Re-importing Exported Data

Exported NDJSON can be imported into any workspace:

curl -X POST "http://localhost:61001/v1/workspaces/ws_newworkspace/import" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @workspace_export.ndjson

Duplicate detection uses content_hash — memories already present in the target workspace are skipped without error.

---

Data Retention

MemoryLayer does not enforce an automatic retention policy by default. Retention is governed by two mechanisms:

Importance Decay

Importance is a float from 0.0 (forgotten) to 1.0 (critical). The decay endpoint reduces importance on demand:

# Reduce a memory's importance by 10%
curl -X POST "http://localhost:61001/v1/memories/mem_abc123/decay" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decay_rate": 0.1}'

Memories with very low importance scores are candidates for archival or deletion in your retention workflows, but MemoryLayer does not delete them automatically — your application must implement that logic.

Pinning

A pinned memory is exempt from decay and will not appear in archival candidate lists. Pin a memory to mark it as permanently important:

curl -X PUT "http://localhost:61001/v1/memories/mem_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pinned": true}'

Retention Recommendations

Memory Type	Suggested Retention Strategy
Episodic	Decay monthly; hard-delete below importance 0.1
Semantic / Procedural	Pin critical facts; decay infrequently
Working (session)	Expire via session TTL; commit to long-term or discard

Automatic retention policy

A server-side configurable retention policy (e.g. auto-delete memories below a threshold after N days) is coming soon.

---

Workspace Isolation

Every memory belongs to exactly one workspace. There is no cross-workspace query or leakage.

How Isolation Works

• Storage layer: Each workspace’s memories, sessions, and associations are filtered by workspace_id at the SQL level. Queries from workspace A cannot access workspace B’s data.
• API layer: Workspace is resolved from the session (X-Session-ID header), the request body (workspace_id field), or defaults to _default. An explicit workspace in the request body overrides session context.
• Authorization: Operations on a workspace require authorization for that specific workspace_id.

Recommended Isolation Patterns

Use Case	Workspace Strategy
SaaS with end users	One workspace per user account
Multi-project agent	One workspace per project or repository
Environment isolation	Separate workspaces for dev, staging, prod
Team / department	One workspace per team

Verifying Isolation

# Memories stored in workspace A are not visible from workspace B
curl -X POST "http://localhost:61001/v1/memories/recall" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "anything", "workspace_id": "ws_workspace_b", "limit": 10}'
# Returns 0 results for data only in ws_workspace_a

The _default Workspace

When no workspace is specified, memories land in _default. This workspace:

• Is auto-created on first use
• Cannot be deleted via the API
• Is suitable for single-user or development deployments

For production multi-user deployments, always specify explicit workspace IDs to maintain isolation and enable clean data deletion per user.