Complete Guide

Agent Playbook

The complete guide to building AI agents with persistent memory.

Quick Start Core Workflows Tool Reference Search Architecture CLAUDE.md Template Usage Contract

1. Quick Start

Get your agent connected to persistent memory in three steps.

Create an Account

Get Your API Key

Navigate to your Dashboard and copy your API key from the settings panel.

Add to MCP Config

Add the lostuplink server to your CLAUDE.md or MCP configuration file.

{
  "mcpServers": {
    "lostuplink": {
      "type": "http",
      "url": "https://lostup.link/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

2. Core Workflows

The three fundamental patterns every agent should follow when working with persistent memory.

Task Lifecycle

start -> brain_begin_task
observe -> brain_append_observation
done -> brain_mark_task_done

Register tasks at the start, log reasoning steps as observations, and always close tasks when finished. Unclosed tasks generate warnings.

Knowledge Management

source -> brain_ingest_document
claim -> brain_learn
image -> brain_ingest_image

Search first to avoid duplicate work. Store durable source documents, concise knowledge claims, and visual content with automatic OCR.

Trust & Safety

confirmed -> brain_reinforce
disputed -> brain_contradict
suspicious -> brain_flag_memory

Keep knowledge accurate. Raise confidence with evidence, record disagreements explicitly, and quarantine suspicious content for review.

3. Complete Tool Reference

All 22 MCP tools grouped by purpose. Click any tool to expand its details.

Task Lifecycle (9 tools)

#1 brain_begin_task Register a new task ▶

brain_begin_task(taskId, title, goal)

Registers your work so other agents can discover, join, or continue it. Returns existing state if the task was already started. Call this at the start of any non-trivial task.

#2 brain_resume_task Load full task state ▶

brain_resume_task(taskId)

Returns the full task state including goal, findings, blockers, and handoffs so you can pick up where you or another agent left off.

#3 brain_append_observation Log reasoning steps ▶

brain_append_observation(taskId, statement, nodeType?)

Logs reasoning steps, hypotheses, discoveries, decisions, and results into the task graph. Builds a reasoning trace so others can follow your logic. nodeType options: OBSERVATION, HYPOTHESIS, DECISION, RESULT, ISSUE, FIX, EVIDENCE, OPEN_QUESTION, PLAN, VERIFICATION.

#4 brain_handoff_task Hand off to another agent ▶

brain_handoff_task(taskId, toAgentId, summary)

Include enough context that the next agent can proceed without re-discovering what you already know. The summary should describe what was done and what remains.

#5 brain_claim_task Take ownership ▶

brain_claim_task(taskId)

Takes ownership of an unclaimed or handed-off task before starting work on it. Prevents multiple agents from working on the same task simultaneously.

#6 brain_release_task Release without completing ▶

brain_release_task(taskId)

Releases your claim on a task without completing it, keeping the task available for others to pick up.

#7 brain_list_recent_task_updates View task history ▶

brain_list_recent_task_updates(taskId, limit?)

Shows what has happened on a task recently. Useful before resuming work or checking on progress.

#8 brain_mark_task_blocked Report blocker ▶

brain_mark_task_blocked(taskId, summary)

Records a blocker so other agents or humans can unblock the work. Use when you hit an issue you cannot resolve yourself.

#9 brain_mark_task_done Complete task ▶

brain_mark_task_done(taskId, summary)

Marks a task as complete. Include a summary of what was accomplished and any follow-up recommendations. Always call this when finished.

Knowledge (8 tools)

#10 brain_search Search with optional graph traversal ▶

brain_search(query, scope?, graphDepth?, limit?)

graphDepth=0 (default): text + vector search only. graphDepth=1: adds 1-hop traversal via SEMANTIC and EVIDENCE edges. graphDepth=2: adds 2-hop traversal. Supports additional filters: subjectKeyPrefix, nodeType, sourceType, since.

#11 brain_task_context Combined search + actions + edges ▶

brain_task_context(taskId)

Returns recent actions, recent writes, and relevant grounded knowledge in one shot. The preferred entry point when resuming a task.

#12 brain_learn Store knowledge ▶

brain_learn(subjectKey, statement, keywords?, visibility?, nodeType?)

Stores a concise knowledge claim. Defaults to PRIVATE visibility. Use keywords for discoverability (synonyms, translations, related terms). Auto-detects sensitive data including API keys, SSN, credit cards, and IBAN.

#13 brain_reinforce Add evidence, raise confidence ▶

brain_reinforce(memoryId, excerpt)

Adds supporting evidence to an existing memory. Raises its confidence score so it ranks higher in future searches.

#14 brain_contradict Record disagreement ▶

brain_contradict(memoryId, statement)

Creates an explicit disagreement record rather than silently overwriting. Lets humans or supervisor agents resolve conflicts.

#15 brain_flag_memory Quarantine for review ▶

brain_flag_memory(memoryId, category, reason)

Quarantines a memory for human review. Categories: HARMFUL, MISINFORMATION, PROMPT_INJECTION, SPAM, IRRELEVANT, ABUSE.

#16 brain_ingest_document Store document with auto-chunking ▶

brain_ingest_document(title, content, sourceType)

Permanently stores a document (article, report, spec) in the knowledge graph with automatic chunking, grounding, and deduplication.

#17 brain_ingest_image Store image with captioning ▶

brain_ingest_image(imageBase64/imageUrl, title?)

Stores an image with automatic captioning, OCR text extraction, and derived facts.

Workspaces & Privacy (5 tools)

#18 brain_list_workspaces List accessible workspaces ▶

brain_list_workspaces()

Returns id, name, and displayName for each workspace this API key has access to.

#19 brain_switch_workspace Activate workspace ▶

brain_switch_workspace(workspaceId?)

All subsequent brain_learn calls with visibility=SHARED target this workspace's namespace. Omit workspaceId to return to private-only mode.

#20 brain_promote_to_workspace Promote private memory (human approval) ▶

brain_promote_to_workspace(memoryId, workspaceId)

Returns a pending token that expires in 10 minutes. A human must confirm the promotion in the UI before the memory is copied. Sensitive memories are permanently blocked from promotion.

#21 brain_mark_sensitive Permanent one-way lock ▶

brain_mark_sensitive(memoryId)

Permanently marks a memory as sensitive. Sensitive memories can never be shared to any workspace. Cannot be undone via API.

#22 brain_review_fading Inspect low-vitality memories ▶

brain_review_fading(limit?)

Returns your lowest-vitality private memories for review. Each result includes access count, evidence count, edge count, and a suggested action. Use this to clean up stale knowledge.

4. Search Architecture

How search results are ranked and how graph-enhanced search discovers related memories.

Scoring Formula

45% Full-text

25% Semantic

20% Confidence

10% Freshness

The final score is computed as: 45% full-text rank + 25% semantic similarity + 20% confidence score + 10% freshness decay, minus a contradiction penalty for disputed memories.

Graph-Enhanced Search

When graphDepth is set to 1 or 2, the search engine traverses SEMANTIC and EVIDENCE edges from top-scoring hits to discover related memories that may not directly match the query text but are structurally connected in the knowledge graph. Graph-discovered results are marked with discoveredVia: "graph:1" or "graph:2".

Keywords Field

The optional keywords parameter on brain_learn improves discoverability by adding synonyms, translations, or related terms that don't appear in the statement itself but should match search queries. For example: "performance speed latency schnell Geschwindigkeit".

5. CLAUDE.md Template

Copy this into your project's CLAUDE.md file to give any agent automatic access to persistent memory.

## LostUplink Shared Memory Network

You have access to a persistent shared memory network via the `lostuplink` MCP tools (brain_*). This is your long-term memory — use it proactively without being asked:

- **Start of every task**: Call `brain_search` to check what is already known before doing redundant work.
- **When you learn something**: Call `brain_learn` for any fact, decision, or conclusion worth preserving across conversations.
- **When you find contradictions**: Call `brain_contradict` if evidence conflicts with existing memory.
- **For multi-step work**: Call `brain_begin_task` at the start, `brain_append_observation` during, and `brain_mark_task_done` at the end.
- **Always close tasks**: Call `brain_mark_task_done` when finished. Unclosed tasks generate warnings.
- **Periodic cleanup**: Call `brain_review_fading` occasionally to inspect low-vitality memories and decide what to keep or remove.

Treat the brain as your primary knowledge store. If you discover something useful, store it. If you need context, search for it. Do not wait to be asked.

6. Vendor-Neutral Usage Contract

This contract is intentionally model-agnostic. Claude, Gemini, Codex, and custom runtimes should all behave the same way when connected to LostUplink.

1. At the beginning of a non-trivial task, read existing context from LostUplink.
2. If a task id is available, call brain.resume_task(taskId) as the main resume entry point.
3. If the task does not exist yet, call brain.begin_task(taskId, title, goal) and then continue.
4. If no task id is available, call brain.search(query) before answering project-specific questions.
5. When a durable source document is encountered, store it with brain.ingest_document.
6. When a concise durable claim is learned, store it with brain.learn or brain.append_observation.
7. When evidence confirms an existing memory, call brain.reinforce.
8. When a result contradicts an existing memory, call brain.contradict instead of silently overwriting.
9. When a task is complete, always call brain.mark_task_done. Unclosed tasks generate warnings.
10. For team-shared knowledge, call brain.switch_workspace then brain.learn with SHARED visibility.
11. To promote private knowledge to a workspace, call brain.promote_to_workspace (requires human approval within 10 min).
12. Mark sensitive data explicitly with brain.mark_sensitive. Sensitive memories can never be promoted.
13. Periodically call brain.review_fading to identify low-vitality memories and clean up stale knowledge.
14. Use brain.flag_memory to quarantine suspicious, harmful, or spam content for human review.
15. Never skip contradictions or blockers just to keep the graph tidy.