Memini Docs

Intake: pushing records into Memini

Memini syncs git repositories and MCP servers with a recipe by itself. Everything else, any chat, mailbox, meeting note-taker or wiki, comes in through one contract, the push API, in one of two ways:

  1. The command line. memini push sends records from a file or from stdin.
  2. Another agent. An agent connected to the person's tools reads them and pushes what it read, with memini push or the HTTP API. The Claude Code skill memini-push tells it how.

Both send the same records: one shape for chat threads and mail threads, one for meetings, one for documents. The contract itself (batches, streams, windows, limits) is in requirements.md, section 4, "One ingest contract" and "Payloads".

Before the first push

On a package-manager server, use the shell shortcut for memini-server cli. The Bash HTTP examples below read bundled fixtures from $MEMINI_RESOURCES. Set it with MEMINI_RESOURCES="$(memini-server path)", or MEMINI_RESOURCES="$PWD" in an extracted release or source checkout.

A push source to push into, and a token that may push (scope ingest). An admin makes both:

memini source add demo chat --kind push
mkdir -p ~/.config/memini
(umask 077; set -C; memini token create --scope ingest --workspace demo --name push > ~/.config/memini/ingest.token)

A token limited to one workspace (--workspace) cannot write anywhere else. Give the pushing client or agent this token only, never an admin one. A source may filter what it stores (channels, domains, authors, automated mail): memini source add --help.

Without an agent

Start with one searchable email conversation. For your own exports, map each complete conversation to a thread, each set of meeting notes to a meeting and each wiki page to a document. The payload examples show what Memini reads. Raw mailbox archives such as MBOX need conversion to these records before import.

For example, use two push sources in the same workspace for work and personal accounts. The source is part of each record's identity, so the same Message-ID can occur in both accounts. Use separate workspaces and workspace-scoped tokens when the accounts need separate access. With the admin token selected, add each source once:

memini source add demo mail-work --kind push
memini source add demo mail-personal --kind push

Reuse mail-work if you created it in the first search walkthrough. Export a folder to your own UTF-8 JSON Lines file (one complete thread per line). In the following example work-inbox.jsonl is that file. Use the ingest token from Before the first push.

MEMINI_TOKEN_FILE="$HOME/.config/memini/ingest.token" memini push --workspace demo --source mail-work --stream inbox --dry-run - < work-inbox.jsonl
MEMINI_TOKEN_FILE="$HOME/.config/memini/ingest.token" memini push --workspace demo --source mail-work --stream inbox - < work-inbox.jsonl

Use mail-personal for the other account's file. Inspect the stored, unchanged and rejected counts. On a rejection, fix the reported field using the source export, then resend. The HTTP walkthrough sends a complete batch and shows the response.

With an agent

For a mailbox or notes app already connected to Claude Code, create the push source and ingest token as above. From the checkout, start the session with the plugin and token:

export PATH="$PWD/bin:$PATH"
MEMINI_TOKEN_FILE="$HOME/.config/memini/ingest.token" claude --plugin-dir integrations/claude-code

Ask, for example, “Use memini-push to import complete conversations from my work mailbox's Inbox for November 2–4, 2026 into workspace demo, source mail-work, stream inbox. Show the stored, unchanged and rejected counts.” The agent needs read access to that mailbox. It reads every page, maps the source fields, dry-runs the records, then pushes them. If a required timestamp or message is missing, inspect the rejected or skipped records before expanding the date range. Search with a read token afterwards.

If the MCP server has a Memini recipe and is available only inside a Claude Code session, use the agent executor. Set up its capture hook, server allowlist and token file, then ask memini-intake to take one stream. The hook forwards raw responses and the service checks the pages and expected replies. If a window is incomplete, its run report identifies which calls are missing.

Scheduled MCP intake

Use this path when the service can reach the MCP endpoint, the recipe matches its tool schema, and the recipe's parser is registered in the service build. An operator first allows the endpoint under MCP service executor settings. From a checkout with the host CLI and an admin token, supply the real URL, recipe file and stream key in the environment variables below. The host CLI can read the local TOML file.

uv run memini recipe validate "$MCP_RECIPE"
uv run memini source add demo team-chat --kind mcp --url "$MCP_ENDPOINT" --recipe "$MCP_RECIPE" --stream "$MCP_STREAM" --schedule 1h
uv run memini sync demo team-chat --wait
uv run memini streams demo team-chat

Check for a successful run and an advancing checkpoint. For a refused endpoint, check the exact operator allowlist. For a short listing or missing replies, read the run report before changing the schedule. The recipe guide walks through a working parser and its completeness checks.

memini push

export MEMINI_TOKEN_FILE=~/.config/memini/ingest.token
memini push --workspace demo --source chat records.jsonl
memini push --workspace demo --source chat - < records.jsonl     # from stdin
some-exporter | memini push --workspace demo --source chat --stream mail/inbox -

With bin/memini, which runs the command inside the service's container, a path names a file in the container, where the host's files are not: send the file on stdin (- < FILE). With the CLI on the host (uv run memini …), both forms work.

The input is UTF-8 JSON or JSON lines:

Option
--workspace NAME, --source NAME where to push; the source is a push source
--stream KEY the stream the records come through: a channel, a mailbox, a list of meetings. Created on first use, shown by memini streams and memini status. A batch in the input may name it instead.
--batch-size N records per request, default 100
--dry-run check every record and print what would be sent; send nothing
--json print the summary as JSON

What it does:

sent 3 records in 1 batch to demo/chat
stored 1 (inserted 0, updated 1, revived 0), deleted 0, unchanged 2
rejected 1:
  line 4 (thread C0PLATFORM/1793699999.000100): payload.messages[0].sent_at: a time with a zone, such as 2026-03-01T09:30:00Z

Exit codes: 0 every record was stored; 1 a record was rejected (the others were sent) or the service refused the push; 2 the arguments or the input are not valid; 3 the service could not be reached, also after the retries; 5 the token was refused.

Records

Every record has the same fields; what is inside payload depends on kind.

Field
kind thread (chat and mail), meeting or document
external_id the record's id in its source, at most 1024 bytes: a channel and the root message's id, a mail thread's first Message-ID, a meeting's id, a page's path. With the source and the kind it makes the record's id.
occurred_at when it happened, with a zone (2026-11-02T09:31:00Z): a thread's latest message, a meeting's start, a document's last change
external_url optional: an http or https link to it in its source
payload the content, a JSON object (below)

Updates are upserts. A record pushed again with the same kind and external_id replaces the stored one; the same record pushed again changes nothing (unchanged). That is how an edited message, a reply that came later or a new version of a page is stored: push the whole record again. A record is replaced whole, never merged: a thread pushed with only its new reply would lose the earlier messages, so a thread is always pushed with all its messages.

Deletes are tombstones. {"kind": "thread", "external_id": "…", "deleted": true}, with no time and no payload, deletes the record; one for a record that was never stored changes nothing.

Names (authors, recipients, participants, speakers, owners) are strings as the source shows them: a display name, a chat user id, or a mail address as Name <address>. people on a thread or a meeting says what the source knows of the names it uses (name and email or chat_user_id), so Memini can tell that the author of a chat message and the sender of a mail are the same person.

Ids inside a record. A message or a transcript segment may carry its source's id; evidence of a decision points at it. Give the source's id when there is one. Without one, Memini derives one from the author and the time (the speaker and the start), which stays the same when the text is edited.

Optional fields that are null or blank count as absent. Fields Memini does not read are kept as sent.

A chat thread with replies

A root message and its replies. external_id is the channel and the root message's id, so the thread is the same record when a reply comes later.

{
  "kind": "thread",
  "external_id": "C0PLATFORM/1793610720.000100",
  "occurred_at": "2026-11-02T09:31:00Z",
  "external_url": "https://chat.example.invalid/archives/C0PLATFORM/p1793610720000100",
  "payload": {
    "channel": "platform",
    "people": [
      {"name": "Ana Example", "chat_user_id": "U01ANA"},
      {"name": "Ben Sample", "chat_user_id": "U02BEN"}
    ],
    "messages": [
      {
        "id": "1793610720.000100",
        "author": "Ana Example",
        "sent_at": "2026-11-02T09:12:00Z",
        "text": "The nightly export timed out again at 03:00 UTC. Shall we move it to 04:30?"
      },
      {
        "id": "1793611860.000300",
        "author": "Ben Sample",
        "sent_at": "2026-11-02T09:31:00Z",
        "mentions": ["Ana Example"],
        "text": "@Ana Example fine with me, the dashboard reads it at 06:00."
      }
    ]
  }
}

A message has author, sent_at and text, and optionally id, recipients (a direct message's other side), mentions and url. A thread may have a channel and a title.

A mail thread with recipients

The messages of one conversation, in order. title is the subject; recipients holds the To addresses and cc the Cc addresses, as the headers say. File: examples/mail-thread.json.

{
  "kind": "thread",
  "external_id": "<20261103101500.4417@mail.example.test>",
  "occurred_at": "2026-11-03T11:02:00Z",
  "payload": {
    "title": "Retention of the archive bucket",
    "channel": "inbox",
    "messages": [
      {
        "id": "<20261103101500.4417@mail.example.test>",
        "author": "Dana Placeholder <dana@example.test>",
        "sent_at": "2026-11-03T10:15:00Z",
        "recipients": ["Ana Example <ana@example.test>"],
        "cc": ["Ben Sample <ben@example.test>"],
        "text": "Hi Ana,\n\nhow long do we keep the nightly exports in the archive bucket? Legal asks for at least 90 days.\n\nDana"
      },
      {
        "id": "<20261103110200.5120@mail.example.test>",
        "author": "Ana Example <ana@example.test>",
        "sent_at": "2026-11-03T11:02:00Z",
        "recipients": ["Dana Placeholder <dana@example.test>"],
        "cc": ["Ben Sample <ben@example.test>"],
        "text": "Hi Dana,\n\nwe keep them for 30 days today. I will raise it to 120 days this week.\n\nAna"
      }
    ]
  }
}

A meeting

title and started_at, and optionally ended_at, participants, summary (Markdown), action_items (strings, or objects with text and optionally owner, due, id) and transcript (segments with text and optionally speaker, start and end in seconds from the start, id). File: examples/meeting.json.

{
  "kind": "meeting",
  "external_id": "notes/2026-11-04-platform-weekly",
  "occurred_at": "2026-11-04T14:00:00Z",
  "external_url": "https://notes.example.invalid/meetings/2026-11-04-platform-weekly",
  "payload": {
    "title": "Platform weekly",
    "started_at": "2026-11-04T14:00:00Z",
    "ended_at": "2026-11-04T14:30:00Z",
    "participants": ["Ana Example", "Ben Sample", "Chloe Placeholder"],
    "summary": "The nightly export now runs at 04:30 UTC. The archive bucket keeps exports for 120 days.",
    "action_items": [
      {"text": "Update the note on the reporting dashboard", "owner": "Ben Sample", "due": "2026-11-06"},
      "Check the export's run time after a week"
    ],
    "transcript": [
      {"id": "s01", "speaker": "Ana Example", "start": 15, "end": 32, "text": "The export moved to 04:30 UTC on Monday and has not failed since."},
      {"id": "s02", "speaker": "Chloe Placeholder", "start": 33, "end": 47, "text": "And the archive keeps them for 120 days now, as legal asked."},
      {"id": "s03", "speaker": "Ben Sample", "start": 48, "end": 55, "text": "I will update the dashboard note by Friday."}
    ]
  }
}

A document

title and text (Markdown). File: examples/document.json.

{
  "kind": "document",
  "external_id": "wiki/runbooks/nightly-export",
  "occurred_at": "2026-11-05T08:00:00Z",
  "external_url": "https://wiki.example.invalid/runbooks/nightly-export",
  "payload": {
    "title": "Runbook: the nightly export",
    "text": "# The nightly export\n\nRuns every night at 04:30 UTC and writes to the archive bucket, which keeps exports for 120 days.\n\n## When it fails\n\nTwo failures in a row page the on-call person. Run it again by hand from the scheduler."
  }
}

The same with curl

memini push is a client of one route, POST /v1/workspaces/{workspace}/sources/{source}/records, whose body is a batch: {"stream": …, "records": […]}. Any client can send it. curl reads the header with the token from a file, so the token is on no command line:

(set -C; umask 077; printf 'Authorization: Bearer %s\n' "$(cat ~/.config/memini/ingest.token)" > ~/.config/memini/ingest.header)
curl -sS -X POST -H @"$HOME/.config/memini/ingest.header" -H 'Content-Type: application/json' \
  --data-binary @"$MEMINI_RESOURCES/docs/examples/thread.json" \
  http://127.0.0.1:6364/v1/workspaces/demo/sources/chat/records

The answer counts what the batch did ("counts": {"inserted": 1, …}) and names its run. A client of the API batches, retries and reads refusals itself; the codes are in src/memini/api/ingest.py and /openapi.json. A client that syncs a stream window by window sends window claims, which move the stream's checkpoint; memini push claims none.

For the mailbox from your first search, the example file is one record. To send it over HTTP, wrap it in the batch object below. Use a header file containing the workspace's ingest token, as above:

{ printf '{"stream":"inbox","records":['; cat "$MEMINI_RESOURCES/docs/examples/mail-thread.json"; printf ']}'; } |
  curl -sS -H @"$HOME/.config/memini/ingest.header" -H 'Content-Type: application/json' \
    --data-binary @- http://127.0.0.1:6364/v1/workspaces/demo/sources/mail-work/records

The reply counts one insertion on an empty source or one unchanged record after the CLI walkthrough. HTTP 422 means the batch or a record failed validation. Check the named field, including timestamps and the records array, before retrying.

Limits

Each a setting of the service (configuration.md):

Limit Default Setting
records and tombstones in one batch 1000 ingest_max_records
the body of one batch 16 MiB ingest_max_body_size
one record's payload, as stored 1 MiB ingest_max_payload_size
writes per minute per token 120 http_rate_limit_writes

memini push stays under the defaults (100 records and 8 MiB a batch) and adapts when the service says a batch is too large. A payload over its limit is rejected: split a very long thread or transcript by time into records of its own.

For agents: the rules

An agent that pushes is a transport, not an author. Memini stores what it is sent, and its guarantees hold only for that: no model rewrites what the source said on the way in (principle 5), and every decision found later points at the message it came from.