HeapFile for VS Code
Connect VS Code agent mode to HeapFile Desktop's local MCP tools and persistent
local memory. The extension is free; installing it does not grant a HeapFile
subscription or paid connector access.
HeapFile keeps the local memory service on your machine. When the installed
desktop runtime is discovered, the extension registers it with VS Code's local
MCP provider. VS Code still controls workspace trust and MCP approval. The
selected AI client decides when to call a tool; installing the extension does
not force HeapFile use on every request.
Start here
What you gain
HeapFile keeps selected project decisions, reasons, constraints, and next steps
available beyond one coding chat. A compatible agent can recall relevant
findings with prepare_work or brain_search, then persist a concise verified
decision with remember. Other authorized clients can retrieve the same
knowledge when connected to the same HeapFile profile and data directory.
This is not automatic cloud synchronization.
The extension discovers the installed local runtime and supplies an MCP
connection. MCP initialization provides HeapFile guidance and tool descriptions;
your client controls which tools the agent can use. Desktop supplies the
runtime and local memory. Editor chat history and project instructions remain
useful alongside HeapFile.
Help your agent use memory consistently
Merge a short routine into the project instructions your selected agent loads:
retrieve relevant HeapFile context before substantive work; save verified
decisions at meaningful milestones within your retention preferences; verify
tool results before claiming recall or persistence.
The agent setup request
asks the agent to inspect existing configuration, preserve unrelated instructions,
add supported setup, and verify the result. For VS Code Local sessions, the
guide includes an optional SessionStart/SubagentStart reminder hook.
This extension does not automatically install project hooks. Other VS Code
session targets and agents outside VS Code use their own supported formats.
Prove it with an invented project
- Ask the agent to call
heapfile_status and verify the intended profile.
- Ask it to use
remember to save a unique fictional project decision,
including its reason and next task. Require recorded=true.
- Open a fresh chat using the same profile and ask
prepare_work to retrieve
that decision. Inspect the tool result, not just the agent's answer.
- Use HeapFile: Show Connection Status → View HeapFile Activity to inspect
recorded reads and confirmed writes from the VS Code-marked MCP process.
Full test prompts and troubleshooting
are available without signing in.
Setup
The HeapFile desktop first-run flow offers to install its bundled VSIX when it
detects VS Code. Its approval prompt explains that after reload the extension
offers HeapFile's local MCP tools to VS Code agent mode in trusted workspaces,
using the current HeapFile profile (Personal by default). It does not change
workspace settings or grant workspace trust. If
the CLI or bundled VSIX is unavailable, install the VSIX manually using
Extensions: Install from VSIX….
The extension looks for HeapFile Desktop's MCP sidecar and registers it with
VS Code. If it is missing, the extension clearly reports Desktop setup;
click the status item or run HeapFile: Getting Started to download Desktop
or locate an existing runtime. After installing Desktop, reopen VS Code if it
has not rediscovered the runtime. When the sidecar is found and setup was not
explicitly declined, the extension uses the Personal profile by default and
registers the MCP provider. The VSIX by itself does not include the desktop
service or silently install a source checkout.
The extension checks these installed-app paths:
- Windows:
%LOCALAPPDATA%/Programs/HeapFile/MCP/HeapFileMCP.exe
- macOS:
/Applications/HeapFile.app/Contents/Resources/HeapFileMCP/HeapFileMCP,
then ~/Applications/HeapFile.app/Contents/Resources/HeapFileMCP/HeapFileMCP,
then a mounted /Volumes/<volume>/HeapFile.app/... bundle (for example,
when HeapFile is launched from its downloaded disk image)
- Linux:
~/Applications/HeapFile/MCP/HeapFileMCP,
~/.local/share/HeapFile/MCP/HeapFileMCP, then /opt/HeapFile/MCP/HeapFileMCP
Windows and Linux also honor the optional HEAPFILE_MCP_EXECUTABLE environment
variable for a nonstandard installation path. Windows checks the normal
per-user install path and both Program Files locations.
If no sidecar is found, select the downloaded HeapFileMCP executable or use
the source fallback. Source setup selects a HeapFile checkout containing
app/mcp_server.py and requirements-mcp.txt. It installs dependencies only
after the user confirms. They go in the isolated ~/.heapfile/mcp-venv
environment; the desktop app's environment is not changed.
The startup prompt can be dismissed or deferred with Later; either choice
leaves setup pending so it can be offered again at a later VS Code launch. To
open it immediately at any time, run HeapFile: Getting Started from the
Command Palette. This command remains available after the startup prompt has
been handled.
- Install HeapFile for VS Code by VTEK Innovations from the
Marketplace,
or use an official bundled VSIX through Extensions: Install from VSIX….
- If HeapFile Desktop is not installed, select Get HeapFile Desktop from
the first-run prompt or run HeapFile: Get Desktop Runtime. Install and
launch the signed desktop app. The prompt stays pending; after reopening VS
Code, select Set Up Connection. This extension does not install the app
or grant workspace trust for you.
- Open a trusted workspace. The installed sidecar is discovered automatically
and offered through the extension's MCP provider. VS Code may ask you to
trust the workspace or approve/enable the MCP server. Run HeapFile: Set Up
MCP Connection only to select a profile or a different runtime.
- Choose Personal (default/recommended) or Expanded local tool access
only when completing manual setup.
Expanded access can expose tools configured on this machine. It does not
unlock HeapFile paid services; cloud connectors and managed features require
the account service to verify a current subscription entitlement.
- For source fallback, confirm the separate-runtime install if the dedicated
environment is missing. The extension verifies that Python can import the
MCP SDK and HeapFile server module before saving setup. Packaged setup uses
the bundled sidecar without modifying the desktop app.
- HeapFile: Verify Local MCP Handshake starts the selected server with the
selected profile, completes MCP initialization, lists its tools, and calls
the read-only
heapfile_status tool. This verifies the local process, not
VS Code's own provider launch or the selected agent's tool use.
- VS Code/agent mode controls when it starts and offers the MCP tools. The
setup flow opens MCP: List Servers after saving the runtime and profile.
Sidecar discovery alone does not prove a live handshake; use HeapFile:
Verify Local MCP Handshake and inspect server logs when you need to
troubleshoot launch.
- Click HeapFile: Ready in the status bar and choose View HeapFile
Activity to see recorded calls from this VS Code MCP process. Successful
prepare_work/brain_search calls are labeled Brain reads. An explicit
remember write is labeled Brain saved only when its result confirms
recorded=true. The bounded local activity log stores tool name, time,
outcome, and category only; it never stores prompts, arguments, or results.
A tool call proves the MCP tool ran, not that the AI relied on its response.
- HeapFile does not automatically save every chat. The AI client must call
remember for a concise, verified decision or finding that should help a
future session. Use it at meaningful milestones or task completion, not on
every turn. The close tool also records a finding and checks session
handoff/stranded work; it is not required for each individual Brain write.
The extension stores the setup kind and selected source or sidecar path in
VS Code's local extension state. The profile and optional data directory are machine-scoped settings.
By default, Personal uses ~/.heapfile/profiles/personal; expanded local access
uses the OS HeapFile application-data directory. The extension passes this path explicitly
so an inherited HEAPFILE_DATA_DIR cannot silently redirect memory. You may
set a different data directory in HeapFile settings. Keep separate
organizations in separate data directories.
From HeapFile: Show Connection Status, select View Plans to see the
HeapFile account and paid connector options. MCP profile selection only controls
local tool/data scope; the HeapFile account service independently verifies paid
access.
Updates and VS Code support
The extension uses VS Code's MCP provider API and supports stable VS Code
1.102.0 and later 1.x releases. VS Code disables auto-update by default for
extensions installed directly from a VSIX. For the published HeapFile Marketplace
listing, run HeapFile: Get Marketplace Updates once to move the
same extension ID in the current VS Code profile to Marketplace management.
VS Code performs the install; the extension does not download arbitrary
packages, uninstall itself, or change VS Code's update settings. The action
stops when automatic update checks are disabled in effective user or
organization policy. If Marketplace install is unavailable or blocked, the
current extension remains in place and the action can be retried later. A
VS Code reload may be required.
After that one-time switch, VS Code owns this extension's updates and follows
the user's and administrator's update preferences. HeapFile Desktop will not
replace the Marketplace-managed extension with its bundled VSIX. VS Code keeps
extension settings and global storage for the same extension identifier.
The public Marketplace listing was verified at version 4.2.3 on 2026-10-05;
check the listing for the current version. Direct VSIX delivery alone does not
enable Marketplace-managed updates. These
extension updates do not update HeapFile Desktop itself; the desktop app has
its own release/update process.
License and paid access
This HeapFile-owned extension is distributed under the proprietary terms in
LICENSE.txt. VTEK's authority over HeapFile-origin extension
files and assets was confirmed by the owner on 2026-10-04. The release workflow
checks the exact VSIX for the proprietary license, third-party notices, and
bundled runtime modules before publication. The current extension has no
third-party runtime package dependencies. The repository has no independent
counsel-approval requirement; the license's review note flags wording that may
merit jurisdiction- or agreement-specific legal advice. The extension is free
to install and does not grant a HeapFile subscription or paid connector access.
Paid services must verify current account entitlement at the service boundary.
Honest connection states
- Packaged: the sidecar executable was found at an installed-app path and
is available from the trusted-workspace MCP provider. Run the local
handshake command to verify that specific installed binary and profile.
- Source: setup verified that the dedicated interpreter can import both
the MCP SDK and HeapFile server module. This does not prove the VS Code-launched
server completed MCP initialization.
- Setup required: neither a configured source runtime nor configured sidecar
is available. If an unconfigured sidecar is discovered, status offers setup.
- Ready: the MCP definition is registered. It does not mean the selected AI
client is connected or that it has called a tool.
- Recent activity: View HeapFile Activity shows calls recorded at the
MCP server boundary from the VS Code-marked process. This proves invocation,
not that an AI relied on returned context. A
remember/close write is
called saved only when the tool result confirms persistence.
The status command reads HeapFile's versioned heapfile.first-run-contract.v1
from a selected source checkout and presents its purpose, first-use rule, and
access boundary. With a packaged sidecar, the contract is not read locally;
the separate verification command still performs a local MCP handshake.
Activity and Brain writes
The status bar reports Ready when the MCP provider is registered; it is
not a live connection claim. View HeapFile Activity shows content-free
evidence of actual calls made through the VS Code-marked MCP process. The
explicit handshake command can verify the selected runtime independently.
Brain retrieval and persistence are separate actions: reads never save a
conversation, and the AI client must call an explicit Brain-write tool such as
remember or close. This preserves user control while making successful
calls and confirmed writes visible.
HeapFile: Remove VS Code Connection removes the configured sidecar/source
path from the current VS Code profile. It keeps HeapFile data and installed runtimes.
Development check
From this directory:
npm test
node --check extension.js
The VSIX can be packaged locally with npm test followed by npx --yes @vscode/vsce@2.26.1 package --no-dependencies --allow-missing-repository --no-rewrite-relative-links --skip-license --out heapfile-vscode.vsix. Direct
VSIX delivery and Marketplace publication are separate release channels; a
Marketplace listing or update is claimed only after it is independently
verified. Release publication must follow product licensing, repository,
signing, and store requirements.
