Hosted memory API

Plug agents into memory without local setup.

Memorylayer exposes a hosted service surface around the Engram engine: workspace API keys, agent bootstrap, an HTTP MCP bridge, downloadable starter skills, and regular JSON endpoints for the memory lifecycle.

OpenAPI API examples Connect guide Agent setup Capabilities Create a workspace

JSON API

Status, search, remember, recent memory, audit history, usage tracking, and bootstrap.

HTTP MCP bridge

One authenticated endpoint for 66 Engram tools with argument hints.

Starter skills

Markdown skills for Codex or Claude-style memory workflows.

auth bootstrap routes bridge

01 / Auth

Workspace key

Private routes accept Authorization bearer tokens or X-API-Key headers.

02 / Bootstrap

Discover the surface

Load workspace URLs, starter skills, MCP tools, and OpenAPI links before wiring clients.

03 / Routes

Use direct APIs

Search, remember, ingest, recent memory, usage, audit, and export are regular JSON endpoints.

04 / Bridge

Call higher-level tools

Use `/mcp` for recall_context, handoff, decisions, entity pivots, and curation tools.

Auth Workspace key via `Authorization: Bearer` or `X-API-Key`

Bridge `/api/workspaces/{slug}/mcp` plus tool discovery and bootstrap

OpenAPI Machine-readable surface for clients that want a direct service contract

This reference covers the hosted API

Memory Layer uses a separate Engram store for each workspace. Its HTTP routes and tool catalog define the available hosted operations. For the engine's native JSONL API and optional MCP adapters, see Engram's documentation.

Mythic cognition in your workspace

Open Cognition from a workspace to create persistent sessions, add planner tasks, record cycles, register assumptions, and review decisions. The saved enabled setting controls new cognition writes without removing history.

Session API

POST /api/workspaces/{slug}/mythic accepts {"operation":"session_start","params":{"project_id":"workspace","goal":"your goal"}}. Use session_list and session_snapshot to resume persistent context.

Memory context

Hosted cycles use bounded lexical workspace search without reinforcing memories. They record planner context; they do not execute tasks or publish generated summaries.

Checks

Registered checks observe Engram connectivity or advertised tool availability. Assumptions can remain unknown, become supported or contradicted, or expire. No host file, shell, or external action checks run.

Decisions

Matching assumptions produce proceed, hold, or revise records. Observations and decision revisions stay in the session. A decision does not execute or authorize an action.

Evidence

Publish a selected recorded observation to Engram explicitly. Client-supplied evidence remains distinct from observed runtime checks.

Memory Layer continues to expose its MCP-compatible HTTP bridge. Engram and Mythic also run independently; their native APIs are separate from the hosted workspace contract.

Evidence records

evidence_put, evidence_get, and evidence_list store and retrieve caller-supplied observations through the workspace bridge. Records retain source and expiry information. They do not execute checks or prove a caller's claim.

Dormant review

dormant_review, dormant_inspect, and dormant_feedback expose the separate review workflow through the same bridge. Automatic dormant collection is off in the hosted runtime; a new workspace can have no candidates to review.

Public discovery

These endpoints are intentionally unauthenticated because they describe the service, not a workspace's private memory.

Service manifest

GET /api/service/manifest

Public route map, counts, and service metadata.

Capabilities

GET /api/capabilities

Capability groups, features, and recipe definitions.

MCP manifest

GET /api/mcp/manifest

Tool groups, argument hints, auth headers, and workspace URL templates.

SDK snippets

GET /api/sdk-snippets

Copyable JavaScript, Python, shell, ingest, and manifest client examples.

Playbooks

GET /api/playbooks

Workflow checklists for handoff, cleanup, onboarding, and investigation pivots.

API examples

GET /api/examples

Request and response fixtures for service discovery, MCP calls, ingest, usage, and export.

Authentication

All workspace API routes accept a workspace key in either `Authorization: Bearer` or `X-API-Key`.

Authorization: Bearer engram_...
X-API-Key: engram_...

Bootstrap

Use one workspace call to discover the rest of the integration surface.

GET /api/workspaces/{slug}/bootstrap

Core endpoints

These are the main hosted routes an agent or service uses day to day.

Status

GET /api/workspaces/{slug}/status

Workspace memory counts and graph stats.

Connect config

GET /api/workspaces/{slug}/connect

Workspace-specific client profile with endpoints, startup calls, skills, and MCP config.

Env block

GET /api/workspaces/{slug}/env

Plain text environment variables for local agents and scripts.

Agent config

GET /api/workspaces/{slug}/agent-config

Codex TOML, Claude skill markdown, env output, endpoints, and starter curl commands.

Codex profile

GET /api/workspaces/{slug}/codex.toml

A workspace-scoped profile for local launchers and Codex-side boot scripts.

Claude skill

GET /api/workspaces/{slug}/claude-skill.md

A markdown skill that teaches Claude-style agents the workspace startup and shutdown routine.

Search

POST /api/workspaces/{slug}/search

Run hosted retrieval without touching the underlying Engram runtime directly.

Remember

POST /api/workspaces/{slug}/remember

Store new narrative, fact, or procedure memories.

Ingest

POST /api/workspaces/{slug}/ingest

Batch import pasted text, JSON items, or pipeline output into workspace memory.

Ingest preview

POST /api/workspaces/{slug}/ingest/preview

Preview split count, sample chunks, and size before writing memory.

Recent

GET /api/workspaces/{slug}/memories/recent

Load the last memories written to the workspace.

Audit

GET /api/workspaces/{slug}/audit

Inspect workspace-level key usage and memory activity.

Usage

GET /api/workspaces/{slug}/usage

Read per-key API activity, route counts, and the latest service calls.

Observability

GET /api/workspaces/{slug}/observability

Read latency, p95, failure rate, slow routes, runtime cache, and recent ingest runs.

Ingest runs

GET /api/workspaces/{slug}/ingest/runs

Inspect source names, item counts, actors, and timestamps for imports.

Recent export

GET /api/workspaces/{slug}/export/recent

Export recent workspace memories as JSON for inspection or a partial export.

MCP bridge

POST /api/workspaces/{slug}/mcp

Call selected Engram tools through one hosted bridge.

Ingestion payload

The batch ingest API accepts either an `items` array or a text `content` field with a split mode: auto, paragraphs, lines, markdown, csv, single, or json.

POST /api/workspaces/{slug}/ingest
{
  "source_name": "handoff.md",
  "source_type": "handoff",
  "items": ["Decision one", "Follow-up two"],
  "layer": "episodic",
  "memory_type": "fact"
}

Quick commands

Copyable requests for the main hosted flows.

Codex-style handoff

curl -H "Authorization: Bearer $MEMORYLAYER_KEY" "$MEMORYLAYER_URL/api/workspaces/$SLUG/bootstrap"

Hosted MCP bridge

curl -X POST -H "Authorization: Bearer $MEMORYLAYER_KEY" -H "Content-Type: application/json" -d '{"tool":"recall_recent","args":{"limit":5}}' "$MEMORYLAYER_URL/api/workspaces/$SLUG/mcp"

Ingestion pipeline

curl -X POST -H "Authorization: Bearer $MEMORYLAYER_KEY" -H "Content-Type: application/json" -d '{"source_name":"handoff.md","items":["Deployment completed","Follow up on billing UI"],"layer":"episodic","memory_type":"fact"}' "$MEMORYLAYER_URL/api/workspaces/$SLUG/ingest"

Usage monitor

curl -H "Authorization: Bearer $MEMORYLAYER_KEY" "$MEMORYLAYER_URL/api/workspaces/$SLUG/usage"

Compact prompt context

curl -X POST -H "Authorization: Bearer $MEMORYLAYER_KEY" -H "Content-Type: application/json" -d '{"tool":"recall_context","args":{"query":"current project state","max_tokens":1200}}' "$MEMORYLAYER_URL/api/workspaces/$SLUG/mcp"

Session checkpoint

curl -X POST -H "Authorization: Bearer $MEMORYLAYER_KEY" -H "Content-Type: application/json" -d '{"tool":"session_checkpoint","args":{"note":"Finished deploy; next check onboarding flow","limit":8}}' "$MEMORYLAYER_URL/api/workspaces/$SLUG/mcp"

Negative knowledge

curl -X POST -H "Authorization: Bearer $MEMORYLAYER_KEY" -H "Content-Type: application/json" -d '{"tool":"remember_negative","args":{"content":"Do not use local SQLite for production memory","scope":"deployment","context":"Postgres is required for hosted workspaces"}}' "$MEMORYLAYER_URL/api/workspaces/$SLUG/mcp"

Entity pivot

curl -X POST -H "Authorization: Bearer $MEMORYLAYER_KEY" -H "Content-Type: application/json" -d '{"tool":"entity_graph","args":{"name":"Memorylayer"}}' "$MEMORYLAYER_URL/api/workspaces/$SLUG/mcp"

Curation pass

curl -X POST -H "Authorization: Bearer $MEMORYLAYER_KEY" -H "Content-Type: application/json" -d '{"tool":"dedup","args":{"threshold":0.92,"max_merges":5}}' "$MEMORYLAYER_URL/api/workspaces/$SLUG/mcp"

Tool manifest

curl "$MEMORYLAYER_URL/api/mcp/manifest"

Public capability sync

curl "$MEMORYLAYER_URL/api/capabilities"

Workspace health check

curl -X POST -H "Authorization: Bearer $MEMORYLAYER_KEY" -H "Content-Type: application/json" -d '{"tool":"health","args":{}}' "$MEMORYLAYER_URL/api/workspaces/$SLUG/mcp"

Bridge tools

The hosted bridge exposes the agent-safe Engram surface: retrieval, handoff, skill selection, curation, and workspace health.

Bridge groups

Tool groups are included in the public MCP manifest and the workspace tool discovery response.

Evidence

3 tools

Dormant review

3 tools

Runtime health

7 tools

Retrieval

10 tools

Entity graph

10 tools

Memory writes

8 tools

Continuity

7 tools

Curation

16 tools

status

Return workspace-level memory counts and graph stats.

health

Check memory indexes, cache state, and workspace runtime health.

memory_map

Build a high-level map of layers, entities, and recent memory activity.

quality_metrics

Return storage quality, curation, and retrieval quality metrics.

count_by

Count memories by layer, source type, entity, or month.

group_by: layer | source_type | entity | month

access_patterns

Show which memories and entities are recalled most often.

limit: integer, optional

reranker_status

Report whether the deep retrieval reranker is trained and available.

recall

Run the main Engram retrieval flow against the workspace.

query: string top_k: integer, optional mode: facts_only | facts_plus_rules | full_context, optional

recall_context

Return a compact context block for prompt injection.

query: string max_tokens: integer, optional

recall_hints

Return short memory hints that trigger recognition without flooding context.

query: string top_k: integer, optional hint_length: integer, optional

recall_recent

Load the most recent memories for the workspace.

limit: integer, optional

recall_entity

Return facts, relationships, and timeline for a named entity.

recall_by_type

Retrieve memories filtered by fact, procedure, or narrative type.

memory_type: fact | procedure | narrative limit: integer, optional

recall_layer

Retrieve memories from one memory layer.

layer: working | episodic | semantic | procedural limit: integer, optional

recall_timeline

Retrieve memories from a date range.

start: YYYY-MM or YYYY-MM-DD end: YYYY-MM or YYYY-MM-DD, optional

recall_related

Traverse related memory context from an entity.

recall_explain

Return retrieval results with scoring and query expansion details.

query: string top_k: integer, optional mode: facts_only | facts_plus_rules | full_context, optional

search_entities

Fuzzy-search entity names for lookup and disambiguation.

query: string limit: integer, optional

entity_graph

Return a JSON subgraph for a named entity.

entity_timeline

Return one entity's memories ordered by date.

backlinks

Find memories that reference or link to a memory.

memory_id: string

find_similar

Find memories semantically similar to a memory.

memory_id: string top_k: integer, optional

focus_brief

Generate a brief about the most relevant memory context for a task.

query: string top_k: integer, optional

layers

Return L0-L3 graduated context for system prompt injection.

query: string, optional max_tokens: integer, optional

get_skills

Select the most relevant procedural skills for a task.

query: string max_skills: integer, optional format: boolean, optional

remember

Store a new memory in the workspace.

content: string layer: string, optional memory_type: fact | procedure | narrative, optional

remember_decision

Store an explicit decision and rationale.

decision: string rationale: string, optional importance: number, optional

remember_error

Store an error pattern with prevention guidance.

error: string prevention: string, optional importance: number, optional

remember_interaction

Store a durable question-and-answer exchange.

question: string answer: string importance: number, optional

remember_negative

Store explicit negative knowledge about what does not exist or should not be done.

content: string scope: string, optional context: string, optional importance: number, optional

remember_project

Update project-level state for the workspace.

name: string status: string, optional location: string, optional notes: string, optional

diary_read

Read the current session diary.

diary_write

Append a concise entry to the current session diary.

entry: string

session_checkpoint

Persist a checkpoint note plus recent state for resumable agent sessions.

note: string, optional limit: integer, optional

session_handoff

Build or save a structured handoff snapshot for another agent/session.

save: boolean, optional limit: integer, optional session_id: string, optional

resume_context

Load the latest handoff snapshot and related recent activity.

session_id: string, optional limit: integer, optional

hotspots

Identify dense or high-interest areas in the memory graph.

hours: integer, optional limit: integer, optional

compare_queries

Compare how two queries retrieve and overlap.

query_a: string query_b: string top_k: integer, optional

export

Export workspace memories as markdown or JSON.

format: markdown | json, optional layer: string, optional limit: integer, optional

compress

Return a compressed summary of retrieved memories for a query.

query: string max_tokens: integer, optional

annotate

Attach an operator note to a memory without changing its content.

memory_id: string note: string

edit_memory

Edit a memory's content and re-embed it.

memory_id: string new_content: string

invalidate

Mark a memory as no longer true.

memory_id: string reason: string, optional

update_status

Move a memory through active, challenged, invalidated, merged, or superseded states.

memory_id: string new_status: active | challenged | invalidated | merged | superseded reason: string, optional

status_history

Return lifecycle history for a memory.

memory_id: string

tag

Add or remove tags on a memory.

memory_id: string add: array, optional remove: array, optional

Pin a memory so retention jobs keep it.

memory_id: string

forget

Soft-delete a memory from the workspace.

memory_id: string

promote

Promote a memory to a higher layer.

memory_id: string target_layer: working | episodic | semantic | procedural

demote

Demote a memory to a lower layer.

memory_id: string target_layer: working | episodic | semantic | procedural

unpin

Remove a pin from a memory.

memory_id: string

link_memories

Manually link two memories through their entities.

memory_id_1: string memory_id_2: string relation: string, optional

update_entity

Add an alias or metadata to an entity.

merge_entities

Merge one entity into another.

source_name: string target_name: string

batch_tag

Add tags to memories matching a search query.

query: string tags: array top_k: integer, optional

dedup

Find and merge near-duplicate memories by similarity.

threshold: number, optional max_merges: integer, optional

detect_communities

Detect entity communities and optionally generate summaries.

min_size: integer, optional generate_summaries: boolean, optional

consolidate

Run a dream cycle to cluster, summarize, and generate peer cards.

extract_patterns

Extract reusable procedural patterns from recent activity.

hours: integer, optional dry_run: boolean, optional novelty_threshold: number, optional

session_summary

Summarize the current session from diary and recent events.

evidence_put

Store an immutable caller-supplied check observation. Does not execute a check or certify its outcome; explicit forgetting is preserved on retries.

project_id: string session_id: string assumption_id: string evidence_id: string outcome: unknown | supported | contradicted observed_at: number expires_at: number observation: object provenance: object source_refs: array, optional

evidence_get

Read one scoped check observation without reinforcing it. Missing/forgotten/inactive sources are unknown; expired evidence is stale.

project_id: string id: string

evidence_list

List scoped caller-supplied observations; exclude forgotten/inactive records. Check each returned state before relying on its reported outcome.

project_id: string session_id: string, optional assumption_id: string, optional limit: integer, optional

dormant_review

Explicitly review metadata-only dormant shadow evaluations; never inject into ordinary recall

limit: integer, optional

dormant_inspect

Explicitly inspect one dormant shadow candidate without reinforcing it; rechecks active/non-forgotten eligibility

event_id: string

dormant_feedback

Record explicit feedback for an inspected dormant candidate. Useful means actually used; silence is never usefulness. Does not change memory importance or access fields.

event_id: string category: useful | irrelevant | dismissed

Starter skills

These skills are available as JSON or plain markdown for agent bootstrapping.

Workspace Memory

Use the hosted workspace memory service for project recall, remember, and recent context.

/api/skills/workspace-memory /api/skills/workspace-memory.md

Session Handoff

Capture the minimum high-value handoff state before stopping work.

/api/skills/session-handoff /api/skills/session-handoff.md

Feature matrix

The full capability index tracks 254 service, site, and agent features.

Open index

Workspace isolation

Each workspace receives its own Engram schema and service boundary.

GitHub login

User identity is handled through GitHub OAuth with no local passwords.

Workspace invites

Issue shareable invites with role-aware membership records.

Scoped API keys

Generate workspace keys for agents, apps, and ingestion pipelines.

API usage trail

Track service calls by route, key, and workspace.

Audit history

Record workspace actions such as keys, invites, memory writes, and bridge calls.

Hosted MCP bridge

Call selected Engram tools through a simple HTTP JSON bridge.

Bootstrap payloads

Discover URLs, headers, tools, and skills from one workspace endpoint.

Starter skills

Download markdown skills that teach agents how to use hosted memory.

Recent memory API

Load the latest workspace memories without custom query code.

Search API

Run hosted retrieval against the real Engram memory graph.

Remember API

Store narrative, fact, and procedure memories over HTTP.

Decision memory

Bridge tool support for durable decisions and rationale.

Project memory

Bridge tool support for structured project state.

Focus briefs

Generate compact task context from the memory graph.

Hotspot detection

Find dense or high-activity regions in workspace memory.

Query comparison

Compare retrieval overlap between two prompts or topics.

OpenAPI contract

Expose the machine-readable API contract for clients.

VPS runtime

Run a warm Python service with direct Postgres access.

Postgres-first storage

Keep app metadata and Engram workspace data in Postgres.

Dashboard search

Search and inspect workspace memory from the browser.

Dashboard write path

Store memories manually when an operator needs to pin state.

Key revocation

Revoke workspace API keys without touching the memory store.

Public service docs

Keep setup, endpoints, bridge tools, and skills documented in-app.

Paste ingestion

Import pasted notes, transcripts, reports, or logs directly from a workspace.

File ingestion

Upload a text, markdown, JSON, or CSV-like file and split it into memories.

Batch ingest API

Push many memories in one authenticated request.

Import run history

Track source, type, item count, and actor for each ingestion run.

Ingest preview

Preview split counts, sample chunks, and payload size before writing memories.

Markdown and CSV splitting

Split imports by headings, rows, lines, paragraphs, JSON items, or one memory.

Recent export

Download recent workspace memories as JSON for inspection or backup.

Connection kits

Generate workspace-specific client config, env blocks, and startup calls.

Agent config API

Expose a normalized JSON profile that agents can read on boot.

Codex profile export

Generate a workspace-scoped TOML profile for Codex-side launchers.

Claude skill export

Generate a workspace-specific markdown skill for Claude-style bootstrapping.

Env template API

Return a copyable .env block for local workers and agent launchers.

Workspace observability

Expose latency, failures, slow routes, top routes, runtime cache, and ingestion history.

Deploy script

Ship a repeatable archive-over-SSH deploy path for the VPS service.

Connect page

Document the shortest path from workspace key to working agent memory.

Architecture guide

Explain the hosted runtime, service metadata, workspace schemas, and Engram boundary.

Use-case library

Show practical memory workflows for coding agents, teams, incidents, research, and automations.

Operations playbook

Document key rotation, audit review, ingestion hygiene, and incident checks.

Integration catalog

Describe how Codex, Claude, custom agents, CI jobs, and scripts connect to hosted memory.