Getting started

Ingest, use, and remove data

Public examples for adding text and files, using memory in prompts, and deleting imported data by id.

Data lifecycle

The Meivo lifecycle is ingest, retrieve, govern, and remove. The memory framework stores normalized content, builds retrieval structures, and can preserve time-aware facts. The supporting enterprise gateway adds source connectors, permission mapping, scheduled sync, rollback, purge, and audit workflows.

Treat a direct-engine space as a namespace, not a security boundary. Any valid direct engine key can address every space. The packaged gateway is the path that derives ACL filters from the authenticated user.

1. Ingest one memory over REST

Keep the returned memory id:

GM_URL=http://127.0.0.1:7437

MEMORY_ID=$(
  curl -sS "$GM_URL/v1/memories" \
    -H 'Content-Type: application/json' \
    -d '{
      "space":"demo",
      "title":"Staging database",
      "content":"The staging database runs Postgres 17 with pgvector."
    }' |
  jq -r '.id'
)

echo "$MEMORY_ID"

The endpoint returns 202 Accepted. Chunking and embedding continue through a bounded background queue, so the record can take a short time to appear in search.

With MCP, use remember and retain its returned memory_id.

2. Choose the correct file-ingestion path

Packaged enterprise ingestion

For governed business data, use the built-in web UI/gateway. Current source connectors cover:

local folders;
Amazon S3;
Google Cloud Storage;
Azure Blob Storage;
IMAP mailboxes.

The ingestion service can normalize supported text, HTML, CSV, JSON, PDF, DOCX, XLSX, PPTX, and email content, then attach source provenance and ACL labels before calling the memory engine. Scanned/image-only documents need an OCR step before Meivo can index their text.

Scheduled and manual source runs preserve run history and support delta sync, rollback, and purge workflows. Use these capabilities when the source system, permissions, and audit evidence matter.

Direct engine ingestion

The direct POST /v1/memories endpoint accepts text; it is not a file parser. An application can extract text itself and post the normalized result:

pdftotext ./contracts/acme-master-services.pdf - |
jq -Rs --arg space contracts \
  --arg source ./contracts/acme-master-services.pdf \
  '{
    space:$space,
    title:$source,
    content:("SOURCE: " + $source + "\n\n" + .)
  }' |
curl -sS "$GM_URL/v1/memories" \
  -H 'Content-Type: application/json' \
  -d @-

For an application-controlled batch, use the run-tagged POST /v1/documents endpoint with already normalized text:

curl -sS "$GM_URL/v1/documents" \
  -H 'Content-Type: application/json' \
  -d '{
    "run_id":"import-2026-07-28",
    "space":"demo",
    "documents":[
      {
        "id":"handbook/security.md",
        "title":"Security handbook",
        "content":"Normalised source text goes here.",
        "mime":"text/markdown",
        "acl_labels":["group:security"]
      }
    ]
  }' | jq

Keep the run_id, external ids, and returned doc_id values. Direct callers are responsible for deriving trustworthy ACL labels and supplying an acl_filter on search; the enterprise gateway performs that work from the authenticated principal.

3. Retrieve evidence or context

Recall mode returns scored chunks and facts:

curl -sS "$GM_URL/v1/search" \
  -H 'Content-Type: application/json' \
  -d '{
    "space":"demo",
    "query":"what does staging run?",
    "mode":"recall",
    "k":8
  }' | jq

Context mode returns a token-budgeted context block and citations:

curl -sS "$GM_URL/v1/search" \
  -H 'Content-Type: application/json' \
  -d '{
    "space":"demo",
    "query":"staging database setup",
    "mode":"context",
    "max_tokens":1000
  }' | jq

For an agent loop:

Retrieve recall results or a context block before the model call.
Pass only the evidence needed for the task to the approved model.
Preserve citations in the answer or decision record.
Store only durable new decisions, facts, or outcomes after the turn.
Post actually used chunk ids to /v1/feedback only when the application can substantiate that use.

With MCP, the equivalent tools are recall, get_context, and remember.

4. Remove active retrieval data

Delete one memory by id:

curl -sS -X DELETE "$GM_URL/v1/memories/$MEMORY_ID"

Roll back a run-tagged direct batch:

curl -sS -X DELETE \
  "$GM_URL/v1/documents?run_id=import-2026-07-28"

Purge a precise set of direct-ingest document ids in one space:

curl -sS "$GM_URL/v1/documents/purge" \
  -H 'Content-Type: application/json' \
  -d '{
    "space":"demo",
    "doc_ids":["0196...","0197..."]
  }'

With MCP, call forget with the id returned by remember.

These operations remove documents and chunks from active retrieval. Current storage migrations also remove provenance-linked facts, generated cards, related graph history, and dependent episodes. Durable graph erasure records coordinate separate graph stores and fence late writers. A pending graph erasure may require retry; verify graph_erasure_pending=false before treating that graph cleanup as complete.

For end-user data, use the enterprise gateway's governed lifecycle. Legal holds block purge, source deletion, and rollback. Pending erasure prevents source re-ingestion, and the purge workflow tracks targets, removes transitive saved answer dependencies, and produces a signed purge record. Holds apply to the gateway; they cannot prevent privileged direct database administration.

Historical records without source provenance, previously downloaded exports, and backups require separate handling. A live-store delete is therefore not a complete personal-data erasure guarantee.

5. Define an erasure and retention runbook

A complete customer deletion process must identify every applicable copy:

live documents and chunks;
derived facts, cards, episodes, and conversation records;
gateway source/run metadata;
tamper-evident audit evidence and exports;
search or observability logs;
database snapshots, object-store versions, and disaster-recovery backups;
the upstream source, which could reintroduce content on the next sync.

Meivo does not claim that one live-store delete call erases all of those copies. For regulated erasure requirements, document the current product boundary, legal basis for retained audit/history, backup expiry, restore-time re-deletion procedure, and any manual database operation. Test the procedure with the customer's data-protection and security teams before making an SLA.

Use a dedicated installation or disposable data directory for clean-room tests that must be destroyed in full.

Minimal TypeScript loop

const GM = "http://127.0.0.1:7437";
const SPACE = "demo";

async function remember(content: string) {
  const res = await fetch(`${GM}/v1/memories`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ space: SPACE, content }),
  });
  if (!res.ok) throw new Error(`remember failed: ${res.status}`);
  return (await res.json()).id as string;
}

async function context(query: string) {
  const res = await fetch(`${GM}/v1/search`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      space: SPACE,
      query,
      mode: "context",
      max_tokens: 1000,
    }),
  });
  if (!res.ok) throw new Error(`search failed: ${res.status}`);
  return (await res.json()) as {
    context: string;
    citations: Array<{
      doc_id?: string;
      chunk_id?: string;
      fact_id?: string;
    }>;
  };
}

async function forget(memoryId: string) {
  const res = await fetch(`${GM}/v1/memories/${memoryId}`, {
    method: "DELETE",
  });
  if (!res.ok) throw new Error(`delete failed: ${res.status}`);
}

Next: Architecture & integration, Security and offline operation, and Configuration reference.