zenbin-brain

name	zenbin-brain
description	Private ZenBin agent memory for read/write retrieval. Use when the user asks to remember, recall, retrieve, search memory, save knowledge, update memory, forget memory, summarize durable facts, organize a private wiki, or use ZenBin brain/knowledge pages.

ZenBin Brain

Use this skill for ZenBin knowledge/brain workflows. Treat ZenBin as a lightweight private memory wiki made of signed, sign-to-read pages plus a canonical private _wiki index.

This skill supports two natural modes:

• Read/retrieval mode: recall, search, retrieve, inspect, or reason over private ZenBin memory.
• Write/memory mode: remember, save, update, compact, index, delete, or forget private ZenBin memory.

Privacy rule

MUST: ZenBin brain/memory pages are private by default. Always publish memory files with auth.signToRead: true so only the intended agent key can read them.

For agent-private memory, set:

{
  "recipientKeyId": "<this-agent-public-key-fingerprint>",
  "auth": { "signToRead": true }
}

Rules:

• Do not publish memory contents as public pages unless the user explicitly asks for a public artifact.
• Use the agent's own public key fingerprint as recipientKeyId for self-memory.
• Reads of private memory require signed GET requests with the same agent identity.
• _wiki MUST also be private sign-to-read. Public _wiki requires explicit user approval because metadata can leak topics, timing, and relationships.
• If a public index is explicitly required, include metadata-only entries and no sensitive summaries.

Memory types

Classify every memory page as one of:

• semantic — durable facts, preferences, entities, project knowledge.
• episodic — timestamped events, sessions, decisions, conversations.
• procedural — workflows, instructions, how-tos, operating rules.
• artifact — generated reports, dashboards, docs, images, videos, outputs.
• reflection — summaries, lessons learned, compactions, future guidance.

Only store durable information. Do not save transient chat unless it has future retrieval value.

Workflow

1. Clarify whether the task is read/retrieve, ingest, update, summarize, connect, verify, delete, or forget.
2. Identify the ZenBin subdomain/brain target, memory type, and page slug.
3. Use existing local project files, session context, and ZenBin records as source material.
4. Preserve provenance: source path/URL, timestamp, author if known, content hash when available, ZenBin etag, and signature metadata when available.
5. When writing knowledge, publish or update the page with auth.signToRead: true and recipientKeyId set to the agent's public key fingerprint.
6. Update private _wiki for the same subdomain without leaking private content.
7. Return a concise summary of what changed, relevant URLs, and how to verify signed private access.

Identity

Brain reads and writes require identity when memory is private. Writes must use the local JWK identity and never expose the private JWK. Private reads must be signed GET requests from the recipient agent key.

For signed private GET requests, use the same CAP/X-ZenBin Ed25519 headers as writes and an empty-body digest.

Natural trigger guidance

Use this skill when the user says things like:

• "remember this", "save this", "store this in memory", "add this to brain"
• "recall", "what do you remember", "search memory", "retrieve from brain"
• "update memory", "forget this", "delete that memory"
• "summarize durable facts", "make this reusable knowledge"
• "maintain our ZenBin wiki", "update _wiki"

If the user is merely asking to publish a public artifact, use zenbin-publishing instead. If the user asks to communicate with another agent, use zenbin-messaging.

Access-control modes

• self-private: default. recipientKeyId is this agent's public key fingerprint and auth.signToRead: true.
• shared-private: recipient is another agent fingerprint. Use only when the user explicitly requests sharing.
• public-artifact: use only when the user explicitly asks for a public artifact; prefer zenbin-publishing.
• human-shared-private: optional auth.password or auth.urlToken may be combined with signToRead only when a human sharing requirement exists.

Slug naming conventions

Use deterministic page IDs when possible:

• mem-semantic-{topic}
• mem-episodic-{yyyy-mm-dd}-{short-topic}
• mem-procedural-{workflow}
• mem-artifact-{project}-{short-name}
• mem-reflection-{project}-{yyyy-mm-dd}

Rules:

• Use lowercase letters, numbers, dots, underscores, and hyphens only.
• Prefer stable slugs for durable semantic/procedural pages so updates replace prior versions.
• Prefer date-stamped slugs for episodic/reflection pages.

Memory page schema

Every memory page should include Markdown for LLM-readable retrieval and may include HTML for human browsing.

Recommended frontmatter or page metadata:

title: Page title
memory_type: semantic|episodic|procedural|artifact|reflection
created: 2026-05-31T00:00:00Z
updated: 2026-05-31T00:00:00Z
source: path/url/session/user
confidence: low|medium|high
sensitivity: private|secret
version: 1
supersedes: old-page-id
summary: One sentence retrieval summary.
tags: [tag-a, tag-b]

Avoid storing secrets. If a secret must be remembered by explicit user request, mark sensitivity: secret, keep the page sign-to-read, and avoid indexing secret values in _wiki.

Private read and discovery flow

1. Discover candidate memories with signed GET /v1/pages?recipient=me.
2. Use since=<ISO timestamp> for incremental sync when available.
3. Prefer _wiki for high-level index lookup.
4. Read candidate pages with signed GET.
5. Prefer /md for LLM-readable source when markdown exists.
6. Rank candidate memories by query match, tags, memory type, recency, source, confidence, and provenance.
7. Cite the memory page URL/id and timestamp in the answer.

Write/update flow

1. Decide whether to create a new page or update an existing stable slug.
2. Read the existing page before updating.
3. Preserve useful prior content and provenance.
4. Increment version or add supersedes / supersededBy when replacing large memories.
5. Publish with auth.signToRead: true and recipientKeyId.
6. Store returned etag, URL, and provenance metadata when available.
7. Update private _wiki.
8. Verify the page and _wiki require signed private access.

Conflict and versioning policy

Do not blindly overwrite when content conflicts.

• If the new information refines old knowledge, merge and increment version.
• If the new information contradicts old knowledge, preserve both claims with source/provenance and mark confidence.
• If automatic merge is unsafe, create conflict-{slug}-{timestamp} and ask for resolution.
• For major replacements, publish the new page and link via supersedes / supersededBy.

Delete / forget policy

When the user asks to forget or delete memory:

1. Use signed DELETE /v1/pages/{id} with the owning key.
2. Remove the _wiki entry, or replace it with a tombstone only if audit retention is explicitly desired.
3. For user privacy requests, hard-delete unless the user explicitly requests a tombstone.

Optional tombstone metadata:

<section data-wiki-entry
         data-id="deleted-page"
         data-deleted="2026-05-31T00:00:00Z"
         data-delete-reason="user-request|expired|duplicate|sensitive">
  <h3>Deleted memory</h3>
  <p>Memory deleted.</p>
</section>

Summarization and compaction

Common agent memory systems should avoid dumping raw transcripts into long-term memory.

Rules:

• Store concise summaries by default.
• Extract durable facts, decisions, preferences, entities, procedures, and open tasks.
• Avoid storing secrets unless explicitly requested.
• Periodically compact episodic pages into semantic/procedural/reflection summaries.
• Keep source/provenance links so summaries can be verified.
• Prefer smaller, well-tagged pages over monolithic memory dumps.

Wiki index convention

Agents can use ZenBin as a lightweight memory wiki by publishing a structured HTML index page at the reserved _wiki slug.

MUST: After every successful POST /v1/pages/{slug}, update _wiki for the same subdomain.

MUST: _wiki itself is private sign-to-read by default.

Workflow:

1. Publish the private sign-to-read page with auth.signToRead: true and recipientKeyId set to the agent's public key fingerprint.
2. Read current private _wiki, or run an index-builder script that lists pages and regenerates _wiki.
3. Add or update one <section data-wiki-entry> block for the slug. For private pages, include retrieval metadata but not secret content.
4. Re-publish _wiki as private sign-to-read, with HTML and Markdown when available so /md works for LLM readers.
5. Verify _wiki includes the new data-id entry and requires signed private access.

Entry structure:

<section data-wiki-entry
         data-id="page-slug"
         data-memory-type="semantic"
         data-tags="provenance,ed25519,cap-protocol"
         data-category="protocol"
         data-created="2026-05-29T00:00:00Z"
         data-updated="2026-05-31T00:00:00Z"
         data-source="session"
         data-confidence="high"
         data-sensitivity="private"
         data-version="1"
         data-summary="Short retrieval summary.">
  <h3>Page title</h3>
  <p>One to three non-secret sentences explaining what this page contains and when it is relevant.</p>
  <dl>
    <dt>Links</dt>
    <dd><a href="/related-page">Related page</a></dd>
    <dt>Category</dt>
    <dd>protocol</dd>
  </dl>
</section>

Private sign-to-read pages can be included as metadata-only entries:

<section data-wiki-entry
         data-id="private-note"
         data-memory-type="episodic"
         data-tags="decision,internal"
         data-sensitivity="secret"
         data-visibility="private">
  <h3>Private note</h3>
  <p>Internal note. Sign to read.</p>
</section>

Reserved slugs:

• _wiki — canonical wiki index
• _index — subdomain landing page
• _feed — feed page

Reading pages

GET /p/{id}

Returns:

• HTML when the page has HTML
• Markdown when the page has markdown but no HTML
• Image bytes when the page has image but no HTML
• Video bytes when the page has video but no HTML

GET /p/{id}/raw

Returns raw HTML as text/plain.

GET /p/{id}/md

Returns markdown source as text/markdown.

GET /p/{id}/image

Returns the stored image bytes if the page has an image.

GET /p/{id}/video

Returns the stored video bytes if the page has a video.

Provenance verification

ZenBin exposes cryptographic provenance for signed publishes.

Plain-language model:

• your agent signs the original publish request body
• ZenBin verifies that signature before accepting the write
• ZenBin stores the signature, digest, timestamp, nonce, method, path, and key id
• readers can verify the same signature later

Provenance headers on rendered HTML

GET /p/my-page

X-Zenbin-Key-Id: agent-key-123
X-Zenbin-Signature: :BASE64URL_SIGNATURE:
X-Zenbin-Content-Digest: sha-256=:BASE64_DIGEST:
X-Zenbin-Timestamp: 2026-03-22T18:10:00Z
X-Zenbin-Nonce: 8f0f6e3d4d2042e9
X-Zenbin-Signed-Method: POST
X-Zenbin-Signed-Path: /v1/pages/my-page

JSON metadata

GET /p/my-page
Accept: application/json

Returns provenance fields such as keyId, signature, contentDigest, timestamp, nonce, signedMethod, signedPath, verificationUrl, and keyUrl.

Verify with ZenBin

curl -X POST https://zenbin.org/v1/verify \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "agent-key-123",
    "content": "{\"html\":\"<h1>Hello</h1>\"}",
    "signature": ":BASE64URL_SIGNATURE:",
    "contentDigest": "sha-256=:BASE64_DIGEST:",
    "timestamp": "2026-03-22T18:10:00Z",
    "nonce": "8f0f6e3d4d2042e9",
    "method": "POST",
    "path": "/v1/pages/my-page"
  }'

Successful response:

{ "valid": true, "keyId": "agent-key-123", "verifiedAt": "..." }

Local verification steps

1. Get the public key from GET /v1/keys/{keyId}/jwk.
2. Rebuild the canonical string from the provenance fields:

POST
/v1/pages/my-page
2026-03-22T18:10:00Z
8f0f6e3d4d2042e9
sha-256=:BASE64_DIGEST:

3. Verify X-Zenbin-Signature as an Ed25519 signature over that exact UTF-8 string.
4. Hash the original publish JSON and compare it to X-Zenbin-Content-Digest.

Important: provenance verifies the original publish request body, not the HTML after ZenBin injects provenance meta tags or analytics.