---
name: seren-memory
description: "Use Seren Memory to retain private agent context across sessions, retrieve relevant prior knowledge, record durable error fixes and preferences, and read governed organizational knowledge without mixing the two privacy domains."
---

# Seren Memory

Use this skill when an agent needs durable private recall across sessions or governed read access to organizational knowledge.

## API

Use this skill alongside the core Seren API skill (`https://api.serendb.com/skill.md`). Successful non-streaming JSON responses use the `{ "data": ... }` envelope.

## Interfaces

Use the Seren Memory MCP tools for authenticated private memory and organizational knowledge operations. The runtime supplies the caller credential and Seren Core adds the audience-bound internal identity context. Use the publisher REST API at `https://api.serendb.com/publishers/seren-memory` for public service metadata. Do not call the service-level `/mcp` route as ordinary JSON REST.

## Session Workflow

1. Call `session_bootstrap` at the beginning of a session when prior project context would help. Set `reviewed_only` to true when the result will be injected automatically; unreviewed memory remains untrusted evidence for deliberate inspection.
2. Call `recall` before asking the user to repeat durable facts, preferences, previous decisions, or known error fixes. Hybrid recall automatically falls back to keyword retrieval when semantic search is temporarily unavailable.
3. For wide scans, use progressive retrieval instead of one large recall: `search_memories` returns compact previews for up to 50 hits, and `get_memories` hydrates up to 25 selected IDs with full content. This keeps broad searches inside a bounded context budget.
4. Call `remember` only for information likely to remain useful in a future session. Captures remain durable when semantic indexing is temporarily unavailable.
5. Use `set_memory_status` to mark reviewed facts canonical, uncertain material draft, and obsolete material deprecated.
6. Call `learn_from_error` after a verified fix is known, not while diagnosis is speculative.
7. Use `process_conversation` only when transcript extraction is appropriate; it creates selected private memories rather than storing the raw transcript.
8. Use `forget` for recoverable removal and `delete_memory` only when permanent deletion is explicitly intended.

## What To Store

Store durable project decisions, stable user preferences, reusable procedures, verified codebase facts, and confirmed error-fix patterns. Do not store transient status, guesses, duplicated source text, raw logs, credentials, private keys, access tokens, or secrets. Keep project-specific memories scoped with `project_id` when available. Use metadata only for compact structured context; it is not a place for arbitrary transcript or tool-output archives.

## Memory Types

- `episodic`: a durable event or completed interaction.
- `semantic`: a stable fact or decision.
- `procedural`: a repeatable workflow.
- `code`: a verified codebase-specific fact.
- `error_fix`: a confirmed failure and resolution.
- `preference`: a stable user preference.
- `skill`: a reusable learned capability or operating pattern.

Choose the narrowest accurate type. Do not use `semantic` as a catch-all for transient content.

## Lifecycle And Sources

Lifecycle and pinning serve different purposes. `canonical` marks reviewed memory that automatic conflict resolution must not replace, `draft` marks unreviewed or derived material, `active` is the normal default, and `deprecated` removes obsolete material from recall without deleting its history. Pinning protects a memory from automatic cleanup. Managed documents use `ingest_document` with a stable `source_kind` and `source_external_id`; repeated ingestion updates the same memory and preserves prior revisions. Seren Notes can provide its ProseMirror document directly. Other connectors, including Notion, should normalize their source into ProseMirror before ingestion and must not place connector credentials in memory content or metadata.

## Privacy Boundaries

Private memory and organizational knowledge are separate authorization and retention boundaries. Private memory belongs to the authenticated user within the authenticated organization and may contain scoped personal or project recall. Organizational knowledge is separated into knowledge domains with independent publications and access grants. Call `knowledge/domains` to discover only the domains available to the current user and agent, then supply the selected `domain_id` to knowledge reads. Omitting `domain_id` selects the default organization domain. Restricted domains require access for both the authenticated user and the authenticated agent; names, classifications, keywords, and record content never grant access. Do not copy results between domains or combine restricted results into a broader domain. When reading, use `recall` for this user's own prior context and `knowledge/search` for curated facts in an authorized domain. Use `knowledge/operations` to discover that domain's additional reads. Never treat a private transcript, sensitive tool call, personal preference, or per-agent recollection as organizational knowledge. Agent identities have read-only access to published organizational knowledge; model, record, domain, and grant administration is restricted to authenticated human identities.

## MCP Tools

- `session_bootstrap`: assemble grouped private context for a new session.
- `remember`: store through conflict resolution, linking, and configured enrichment.
- `recall`: hybrid-search private memory with automatic keyword fallback.
- `search_memories`: hybrid-search returning compact previews for progressive retrieval.
- `get_memories`: fetch up to 25 memories by ID with full content in request order (REST callers use `GET /memories?ids=`).
- `ingest_document`: create or update a source-managed rich document.
- `append_memory`: append content while preserving revisions.
- `list_memory_revisions`: inspect prior revisions.
- `set_memory_status`: set active, draft, canonical, or deprecated lifecycle.
- `link_memories`, `unlink_memories`: manage explicit typed connections.
- `process_conversation`: extract structured private memories from a transcript.
- `learn_from_error`: store a verified error-fix pattern.
- `forget`: soft-delete private memory.
- `get_memory_graph`: inspect related private memories.
- `create_memory`: insert directly without conflict resolution or enrichment.
- `get_memory`, `update_memory`, `list_memories`: operate on private memory records.
- `delete_memory`: permanently delete a private memory.
- `delete_memories_by_source`: permanently erase retained conversation sources and their derived memories by source identity, returning audit counts.
- `consolidate`: summarize and clean up older private memories.
- `configure_publishers`: enable approved enrichment or retrieval publishers. Publisher integrations may receive memory-derived content, so configure only publishers authorized for that data.

## Known Gotchas

1. Caller-supplied `org_id` cannot switch organizations; authenticated identity always wins.
2. `remember` may update, delete, or no-op instead of inserting when conflict resolution finds an existing memory. Inspect `action_taken`. Canonical and pinned memories are protected; conflicting content is stored as a draft instead.
3. `create_memory` bypasses conflict resolution and enrichment; prefer `remember` for normal use.
4. `forget` is recoverable soft deletion, while `delete_memory` and `DELETE /memories/{id}` are permanent. `delete_memories_by_source` is also permanent and cascades: it erases matched retained transcripts and their derived memories together. It requires at least one of `source_external_id` / `source_uri`, so it can never widen into an unscoped wipe.
5. Recall quality depends on accurate project scope, memory type, and optional time bounds. Convert phrases such as `last week` into explicit UTC `created_after` and `created_before` values before calling recall. Check `signals.semantic_available` when explaining degraded recall.
6. A source-managed memory must be changed by re-ingesting its stable source identity; direct update and append operations are rejected.
7. A stable `source_external_id` always stores a metadata source envelope for idempotent capture; `retain_source` controls only whether the raw transcript payload is kept. Only extracted memories enter recall. The `hook:` and `import:` identifier namespaces are reserved for agent capture and migration.
8. Organizational knowledge may be unavailable when its selected domain has not been published or the current user-agent pair is not authorized. Do not fall back by copying knowledge from another domain or private memory into shared knowledge.
9. The REST API wraps successful JSON payloads in `data`; MCP tool results are protocol-native JSON strings.
10. `GET /memories?ids=` selects at most 25 exact members and cannot be combined with the other list filters. REST omits inaccessible IDs without a `missing` array; the `get_memories` MCP tool reports those IDs in `missing`.

## Memory Workflows

Store and retrieve private agent memory through higher-level operations.

Assemble private memory context for the start of an agent session.

### POST `/bootstrap`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/bootstrap" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"123e4567-e89b-12d3-a456-426614174000","token_budget":4000}'
```

Persist a private memory with conflict detection, linking, and configured enrichment.

### POST `/remember`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/remember" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"This project uses PostgreSQL 16","memory_type":"semantic"}'
```

Search private memory using hybrid vector, full-text, and relationship signals.

### POST `/recall`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/recall" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"database migration conventions"}'
```

Search private memory and return compact previews for progressive retrieval.

### POST `/memories/search`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/memories/search" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"database migration conventions"}'
```

Extract structured private memories from a conversation transcript.

### POST `/process_conversation`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/process_conversation" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transcript":"User confirmed that production migrations require explicit rollback notes."}'
```

Capture policy-approved prompt and assistant-response fields idempotently from a lifecycle hook using the reserved hook: source namespace.

### POST `/capture_agent_turn`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/capture_agent_turn" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_platform":"claude","source_external_id":"hook:agent-turn:claude:conv-1:turn-4","policy_version":"baseline"}'
```

Store a private error-and-fix pattern for future retrieval.

### POST `/learn_from_error`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/learn_from_error" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"error_content":"Migration failed because the extension was missing","fix_content":"Install the extension before applying the migration"}'
```

Soft-delete a private memory so it no longer appears in normal retrieval.

### POST `/forget`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/forget" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"memory_id":"123e4567-e89b-12d3-a456-426614174000"}'
```

Ingest or update a rich document using a stable external source identity.

### POST `/ingest/document`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/ingest/document" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document":{},"memory_type":"","source_external_id":"","source_kind":""}'
```

## Memory Records

Inspect or permanently remove individual private memory records.

List private memories with scope, type, pin, consolidation, limit, and offset filters, or select exact members with ids.

### GET `/memories`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-memory/memories" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Export a portable page of private memories and retained conversation sources.

### GET `/memories/export`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-memory/memories/export" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Permanently erase retained conversation sources and their derived memories by stable source identity.

### DELETE `/memories/by-source`

```bash
curl -sS -X DELETE "https://api.serendb.com/publishers/seren-memory/memories/by-source" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"org_id":"<org_uuid>","project_id":"<project_uuid>","source_external_id":""}'
```

Fetch one private memory owned by the authenticated user and organization.

### GET `/memories/{id}`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-memory/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Permanently delete one private memory. This cannot be undone.

### DELETE `/memories/{id}`

```bash
curl -sS -X DELETE "https://api.serendb.com/publishers/seren-memory/memories/$MEMORY_ID" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Append content to one private memory while preserving its revision history.

### POST `/memories/{id}/append`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/memories/$MEMORY_ID/append" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":""}'
```

List the preserved revision history for one private memory.

### GET `/memories/{id}/revisions`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-memory/memories/$MEMORY_ID/revisions" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

List dated relationship versions for one private memory, optionally at a point in time.

### GET `/memories/{id}/timeline`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-memory/memories/$MEMORY_ID/timeline" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Set a private memory lifecycle independently from its pin state.

### PUT `/memories/{id}/status`

```bash
curl -sS -X PUT "https://api.serendb.com/publishers/seren-memory/memories/$MEMORY_ID/status" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lifecycle_status":""}'
```

Promote or demote a private memory review status through an explicit transition.

### PUT `/memories/{id}/review`

```bash
curl -sS -X PUT "https://api.serendb.com/publishers/seren-memory/memories/$MEMORY_ID/review" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"review_status":""}'
```

Create an explicit typed connection between two private memories.

### POST `/memories/connections`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/memories/connections" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"edge_type":"","source_id":"<source_uuid>","target_id":"<target_uuid>"}'
```

Remove an explicit typed connection between two private memories.

### DELETE `/memories/connections`

```bash
curl -sS -X DELETE "https://api.serendb.com/publishers/seren-memory/memories/connections" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"edge_type":"","source_id":"<source_uuid>","target_id":"<target_uuid>"}'
```

## Organizational Knowledge

Use the organization's governed, read-only knowledge product.

List only the organizational knowledge domains available to the current user and agent.

### GET `/knowledge/domains`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-memory/knowledge/domains" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Search shareable organizational knowledge using a curated stored query.

### POST `/knowledge/search`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/knowledge/search" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"release approval process"}'
```

Open one organizational knowledge entity by its stable entity ID.

### POST `/knowledge/entities/open`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/knowledge/entities/open" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity_id":"service:seren-memory"}'
```

List the organization's published knowledge operations.

### GET `/knowledge/operations`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-memory/knowledge/operations" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Invoke an organization-defined read-only knowledge operation.

### POST `/knowledge/operations/{operation_name}`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/knowledge/operations/$OPERATION_NAME" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parameters":{}}'
```

## Maintenance

Inspect service synchronization state or trigger private-memory consolidation.

Preview a tenant-scoped workspace merge and receive a state-bound plan hash without changing records.

### POST `/workspaces/merge/preview`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/workspaces/merge/preview" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source_workspace_key":"","target_workspace_key":""}'
```

Execute a reviewed workspace merge, retain an alias for future capture, and record an immutable audit row.

### POST `/workspaces/merge`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/workspaces/merge" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan_hash":"","source_workspace_key":"","target_workspace_key":""}'
```

Create a durable import migration record for external memory corpora.

### POST `/migrations`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/migrations" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expected_record_count":0,"plan_hash":"","source_instance_id":"","source_type":""}'
```

Inspect one migration's state, counters, and attributed record counts.

### GET `/migrations/{id}`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-memory/migrations/$MEMORY_ID" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Import a batch of already-extracted records idempotently under a migration.

### POST `/migrations/{id}/records`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/migrations/$MEMORY_ID/records" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"records":[{"agent_platform":"","content":"","external_parent_session_id":"","memory_type":"","source_external_id":""}]}'
```

Generate a bounded batch of embeddings for imported migration records.

### POST `/migrations/{id}/embeddings`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/migrations/$MEMORY_ID/embeddings" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":0}'
```

Transition a migration lifecycle state.

### PUT `/migrations/{id}/state`

```bash
curl -sS -X PUT "https://api.serendb.com/publishers/seren-memory/migrations/$MEMORY_ID/state" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"state":""}'
```

Remove only the records created by a migration run or series.

### POST `/migrations/{id}/rollback`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/migrations/$MEMORY_ID/rollback" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"series":true}'
```

Inspect the private-memory API synchronization status and service version.

### GET `/sync/status`

```bash
curl -sS -X GET "https://api.serendb.com/publishers/seren-memory/sync/status" \
  -H "Authorization: Bearer $SEREN_API_KEY"
```

Manually consolidate old private memories for the authenticated scope.

### POST `/jobs/consolidate`

```bash
curl -sS -X POST "https://api.serendb.com/publishers/seren-memory/jobs/consolidate" \
  -H "Authorization: Bearer $SEREN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id":"123e4567-e89b-12d3-a456-426614174000"}'
```