Connect your agents to HeapFile memory

Connect the client, then establish the routine

HeapFile exposes memory tools through MCP. Its local stdio connection starts a HeapFile process for the client; it is not a public network endpoint that every agent automatically discovers. An open Desktop window alone does not configure another client.

1. Install the available HeapFile Desktop release and choose the client setup offered by that installation. In VS Code, use HeapFile for VS Code.
2. Register or enable HeapFile through that client's supported MCP setup. Use the actual installed runtime path and its generated connection settings; do not guess a port or download private source code.
3. Call heapfile_status and confirm the intended profile. Clients sharing memory need the same authorized data directory. Keep separate organizations separate.
4. Check that the client exposes prepare_work, brain_search, and remember, or its documented discovery route for those tools. MCP initialization supplies HeapFile guidance, but each client decides how to use it.
5. Add the memory routine below to supported project instructions. Enable an optional hook only when its client, event schema, installed command, and trust state are verified.

For a generic local stdio client, configure the discovered HeapFileMCP executable as the server command with the intended HEAPFILE_PROFILE and HEAPFILE_DATA_DIR. Configuration file shape differs by client; prefer HeapFile's setup flow and the client's documentation over copying another client's JSON.

Which setup applies?

The connector reference records capability scope and readiness. A product name in that catalog is not proof that your account or device is connected. Do not expose a local memory service publicly merely to make a remote agent reach it.

A shared memory instruction

Merge this into the instruction file your client actually loads. Keep existing project guidance. For VS Code Copilot, use .github/copilot-instructions.md; for compatible clients, a root AGENTS.md can hold shared project guidance.

Use HeapFile as this project's durable memory when its tools are available.
Before substantive work, call prepare_work with the project and task.
Use brain_search for a specific prior decision when relevant context is missing.
Verify retrieved context against current evidence and the user's request.
At a meaningful milestone, call remember with a concise verified decision,
its reason, source context, and next step, within the user's retention preferences.
Do not save secrets, entire transcripts, or unrelated personal/company data.
Only report a saved memory when the write result confirms persistence.
If HeapFile is unavailable, say so and continue work that does not depend on it.

Instructions express the working routine. MCP supplies tools. Hooks run at supported lifecycle events. A hook reminder can prompt tool use, but only a successful tool result establishes that recall or saving happened.

Ask your agent to configure the project

Paste this into the client you want to configure. It asks the agent to inspect the current installation and merge compatible setup, rather than assume every client shares VS Code's hooks.

Configure this project to use HeapFile as durable memory in my current AI client.
First identify the client, session target, version, execution host, and existing
MCP connection. Verify heapfile_status and the intended profile/data directory.
Inspect existing project instructions and hook files; preserve unrelated content.
Merge the recall-and-save routine from https://heapfile.com/agent-setup.html
into the instruction format this client actually loads.
For VS Code Local, offer the documented SessionStart memory reminder;
include SubagentStart only if this session supports it. For other clients, use
their own supported HeapFile setup and hook schema. Do not invent commands,
copy another client's hook format, weaken approvals, or expose a local service.
Apply supported local setup within my permissions, show the exact changes,
and tell me if a client restart or hook-trust action is necessary.
Use invented data to verify a confirmed remember write and a fresh-session recall.
If you cannot open a fresh session, give me the one test prompt to run there.
Report connection, hook delivery, memory write, and recall separately.
If a hook is unsupported, keep MCP plus project instructions working and say so.

The agent should produce concrete configuration changes and verification results. If it lacks file access or the required client controls, it should identify that precise gap and preserve the working MCP connection.

Optional reminder hook for VS Code Local

This recipe targets VS Code's Local session target. Hook support depends on the selected agent runtime and VS Code version. Copilot on Agent Host, Claude, and Codex use their own hook contracts. Select your target before opening Chat: Configure Hooks; consult the VS Code hooks guide.

This sample adds a memory reminder at session and subagent start. It does not read memory, save chats, or install a HeapFile runtime. It requires Node.js on the hook execution host. Review the files before enabling them and preserve any existing hooks.

Merge into .github/hooks/heapfile-memory.json. Omit the SubagentStart entry if unsupported or unnecessary.

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "node .github/hooks/heapfile-memory.cjs SessionStart",
        "timeout": 5
      }
    ],
    "SubagentStart": [
      {
        "type": "command",
        "command": "node .github/hooks/heapfile-memory.cjs SubagentStart",
        "timeout": 5
      }
    ]
  }
}

Create .github/hooks/heapfile-memory.cjs with this reminder:

'use strict';
const event = process.argv[2];
if (['SessionStart', 'SubagentStart'].includes(event)) {
  process.stdout.write(JSON.stringify({
    hookSpecificOutput: {
      hookEventName: event,
      additionalContext: 'Use available HeapFile tools to recall relevant project context before substantive work. Save concise verified decisions with remember at meaningful milestones, within the user retention preferences. Confirm tool results; if unavailable, say so and continue independent work.'
    }
  }) + '\n');
}

The sample reads no files or transcript content, makes no network request, and registers no stop-blocking hook. Unknown event arguments emit nothing. Its output follows the Local hook reference. This is an opt-in project recipe, not a hook automatically installed by the HeapFile extension.

Check hook discovery and output in a fresh Local session, then inspect the actual HeapFile tool calls. Hook delivery and memory persistence are separate checks. Remove only these entries and their script to undo this recipe.

Verify once, then reuse the workflow

1. Confirm the client can call HeapFile status in the intended profile.
2. Save a unique invented project decision using remember. Require recorded=true before calling it saved.
3. In a fresh session, retrieve that decision with prepare_work or brain_search. Check the returned evidence.
4. For cross-client use, repeat recall in the second client connected to the same authorized data. For hooks, separately confirm a real lifecycle event delivered the expected reminder or context.

Use the VS Code test prompts or the general context guide. If the client cannot open another session itself, it should give you the exact next-session test instead of claiming it ran.

Automatic recall hooks do not mean automatic retention of every conversation. Use explicit, verified writes within your preferences. Memory returned to an agent may be processed by that agent's model provider. Shared local data is not automatic cloud synchronization or a paid-feature entitlement.