HeapFile Context Handoff

Before You Start

New to HeapFile? Open your HeapFile account to review sign-in, current download options, and access requirements. Use the desktop installation guide for setup, then connect HeapFile to a compatible AI client through MCP and confirm remember and prepare_work are available.

These examples are HeapFile tool calls and their JSON arguments. Ask your connected AI client to make the calls; they are not terminal commands. Tool names and connection setup may appear differently in your client.

Use the same HeapFile memory profile for saving and recalling. A different client must connect to that same profile to read the saved note. This guide uses only invented project details; review your selected AI provider and permissions before using real project material.

What the Synthetic Demo Established

In a connected-tool demonstration on October 4, 2026, an invented project called Lantern Notebook saved a decision to export plain Markdown, a constraint to use invented sample notes, and a next task to check the export in two editors. remember returned recorded: true. A subsequent prepare_work call returned MATCHES_FOUND with one matching finding and source: local_memory.

That demonstration used the same session. Fresh-session recovery, another provider, an installed desktop journey, and offline behavior were not tested. The editor check was not performed. The finding was labeled client-submitted and not independently verified. The Lantern Demo walkthrough below is a separate exercise for you to run and check; it is not a verified fresh-session result.

1. Save One Clear Decision

Imagine you are building Lantern Demo, a tiny task-list app. Your decision is to keep the first version in one HTML file so the prototype stays easy to review. Your constraint is no login. Your next task is a keyboard test.

Ask your client: Use HeapFile's remember tool to save the following synthetic decision for Lantern Demo. Show the actual tool response.

{
  "problem": "What did we decide for Lantern Demo?",
  "finding": "Synthetic project: Lantern Demo is a task-list prototype. Decision: keep version one in a single HTML file so it is easy to review. Constraint: no login. Next task: test adding and completing a task with the keyboard.",
  "workstream": "Lantern Demo synthetic handoff",
  "evidence": "Invented exercise note; not a real product test."
}

Check the save: look for recorded: true and an episode_id in the actual response. Keep that ID with your test notes. A chat reply saying saved without a tool response does not establish that HeapFile recorded it.

For real work, record the decision, its reason, and the evidence you actually checked. Keep a proposed next task distinct from a completed test.

2. Recall It in a Fresh Session

Start a new AI session with the same HeapFile connection and memory profile. Leave the saved finding out of your new prompt so you can see whether it is retrieved.

Ask your client: Use HeapFile prepare_work to retrieve our Lantern Demo decision before planning the next task. Show the returned context and explain where it came from.

{
  "question": "What did we decide for Lantern Demo, what is the constraint, and what should we test next?",
  "workstream": "Lantern Demo synthetic handoff"
}

prepare_work retrieves context relevant to the question. It does not automatically transfer an entire previous conversation. In a personal memory profile, a matching response can report MATCHES_FOUND, with findings and source: local_memory. Inspect the returned text rather than assuming every call finds the right note.

3. Check What Came Back

Your first successful handoff is a saved note retrieved in a fresh session with the details below. These are the expected contents of this exercise, not a sample response or a live receipt.

Have the client propose the keyboard test from that context. Review the proposed work before taking action: a recalled next task is context, not authorization to run it.

Try a Changed Decision

Save another synthetic finding in the same workstream: Update for Lantern Demo: the latest decision is two HTML files to separate the task list from its help page. This supersedes the earlier single-file decision. No login remains the constraint. Then ask prepare_work for the latest decision. Check whether the client identifies the update and its evidence. Older and newer notes may both appear; saving an update is not a promise that the old finding disappears.

If the Handoff Does Not Work

• No HeapFile tools: check the client connection and installation guidance. A text answer alone does not verify a connection.
• No saved receipt: inspect the remember response before continuing. A failed save cannot establish a reusable handoff.
• NO_LOCAL_CONTEXT: confirm the same profile is connected, then retry with Lantern Demo and the exact workstream. If needed, ask the client to use brain_search with that project name. Report a miss when the saved note is still absent.
• NEEDS_CLIENT_EVIDENCE: in a configuration that uses external sources, the packet may request missing evidence. Supply only the requested material you are authorized to access; a request does not grant access.
• Stale or conflicting context: compare the finding, date, and evidence with the current project. Ask the client to state what remains uncertain.

Still stuck? Contact HeapFile support with the app version, client, and a sanitized description of the failure. Keep private project content and credentials out of screenshots and reports.