Project memory for your coding agent

What the extension gives you

The extension connects VS Code's agent tools to the HeapFile runtime installed with HeapFile Desktop. It uses Model Context Protocol (MCP), the interface through which an agent discovers and calls HeapFile tools. The extension is the connection; Desktop supplies the local service and memory.

• Recall: retrieve relevant saved project decisions with prepare_work or search for a specific finding with brain_search.
• Save: record a concise, verified decision with remember, including its reason and source context.
• Continue: bring that saved context into a fresh session using the same authorized HeapFile profile and data directory.
• Check: inspect local connection status and recorded tool activity instead of guessing whether memory was used.

Use HeapFile alongside your editor's chat history and project instructions. Its value is an explicit, reusable store of selected project knowledge. It does not replace the editor, increase a model's context window, or guarantee that every agent uses memory automatically.

Set up once in desktop VS Code

1. Install and launch HeapFile Desktop. Account and download requirements are shown in the account portal.
2. Install HeapFile for VS Code by VTEK Innovations from the Visual Studio Marketplace. The extension identifier is vtek-innovations.heapfile-vscode. Use VS Code 1.102 or a later supported 1.x release.
3. Open your project. In a workspace you trust, the extension discovers the installed HeapFile runtime and registers its MCP provider. The default profile is Personal. Complete VS Code's workspace and server approval prompts as appropriate.
4. If setup needs attention, open the Command Palette and run HeapFile: Getting Started. Use HeapFile: Set Up MCP Connection to choose a runtime or profile. Reopen VS Code after installing Desktop if needed.
5. Run MCP: List Servers and check that HeapFile is enabled. Open an agent session that supports VS Code's MCP tools and check its available tools. Other agent extensions may have their own MCP configuration.

Normal packaged setup does not require a source checkout or a hand-written MCP configuration. The extension does not install Desktop or grant workspace trust for you. Its Marketplace installation is free; AI-provider usage, HeapFile accounts, and paid features have their own access requirements.

How agents discover HeapFile

The extension registers a local HeapFile server with VS Code. When the client starts it, MCP initialization provides HeapFile guidance and tool descriptions. A compatible agent can then discover the memory tools and choose to call them. VS Code and the selected client control tool availability and approvals.

Discovery, recall, and saving are separate steps. A registered server makes tools available; a retrieval call reads saved context; a successful write persists a finding. Installing the extension does not silently save all chats or force a tool call on every request. The project instruction below helps establish a consistent routine.

For client-specific setup, see the connector reference. An agent running in another extension, on another machine, or in a remote environment must have its own supported connection to the intended HeapFile data.

Prove save and recall with an invented project

Use this small exercise before relying on HeapFile for real work. Give your test a unique project name so an older example cannot be mistaken for today's result.

1. Ask the agent: Call HeapFile's heapfile_status and tell me which profile is active. Do not save anything yet. Confirm it is the profile you intended.
2. Ask: For the invented project Harbor Demo 47, use HeapFile remember to save this decision: use SQLite for the local prototype because it must work offline. The next task is to test backup and restore. This is test data. Confirm whether the tool reports recorded=true.
3. Check the actual tool result. Then click the HeapFile status item, choose View HeapFile Activity, and look for a confirmed Brain saved event.
4. Start a fresh agent chat with the same HeapFile profile and data directory. Ask: Use HeapFile prepare_work to retrieve the saved decision for Harbor Demo 47. What was chosen, why, and what is the next task? If it finds nothing, search HeapFile Brain for Harbor Demo 47 and say what is missing.
5. Confirm the returned context contains SQLite, offline use, and the backup-and-restore next task. Inspect the retrieval tool result; a plausible answer alone is not proof of recall.

A local handshake verifies the service separately: run HeapFile: Verify Local MCP Handshake. It initializes the selected runtime, lists tools, and calls read-only status. It does not prove that your chosen agent has used those tools.

Give your project a memory routine

Merge this optional instruction into your existing project guidance. For Copilot, use .github/copilot-instructions.md; a root AGENTS.md is another option for clients that support it. Preserve your existing instructions and check that the selected client loads the file.

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 earlier decision when more context is needed.
Check retrieved evidence against the current request and repository state.
At a meaningful milestone, use remember for a concise verified decision,
its reason, source context, and next step, within my retention preferences.
Do not save secrets, whole chats, or unrelated personal or company data.
Confirm persistence from the tool result before saying something was saved.
If HeapFile is unavailable, say so and continue work that does not need it.
Never claim a memory read or write without the corresponding tool result.

This instruction guides the agent; it does not grant tool access or override approvals. See VS Code's instruction-file documentation for client-specific loading behavior.

Ask your VS Code agent to add instructions and hooks

Use the copyable agent setup request to have your agent inspect this project's configuration, merge the memory routine, and verify the connection. The optional VS Code Local hook recipe adds reminders at session and subagent start.

The HeapFile extension does not automatically install these project hooks. Choose the correct session target and use its supported hook format. Agents outside VS Code can follow the same MCP and memory setup guide with their own client configuration.

Know what each status proves

The bounded activity log records tool names, times, outcomes, and categories, without storing the prompts, arguments, or returned content. Activity proves invocation, not that a model relied on the result.

When it does not work yet

• Desktop setup or runtime missing: install and launch Desktop, reopen VS Code, then use Getting Started to locate the runtime if needed. The extension alone does not contain the Desktop service.
• Ready but no agent tools: check workspace trust, MCP server enablement, and your agent's tool selection. Use MCP: List Servers and its output logs. A different agent extension may require a separate connection.
• Handshake fails: confirm the selected runtime and profile with Show Connection Status. Share the error category with support after removing private paths and content.
• No recalled decision: verify that the original write succeeded and both sessions use the same authorized profile and data directory. Search by the unique project name.
• Remote host warning: a remote workspace host cannot launch a local HeapFile executable. Use the extension in the local desktop UI host or reopen the project locally; do not assume a browser-only or remote session has local memory access.
• Installed from a VSIX: run HeapFile: Get Marketplace Updates to request the same extension's Marketplace installation. VS Code and organization update policies control updates. Desktop updates remain separate.

More help: VS Code MCP server management and HeapFile support.

Choose what you retain and share

HeapFile's local memory lives in the configured profile/data directory. Keep separate organizations in separate directories. Compatible clients can recall the same stored knowledge only when connected to that same authorized data; this is not automatic cloud synchronization.

When an agent reads memory, returned context becomes available to that client and may be sent to its selected model provider under the client's settings. Local storage does not mean every downstream AI request stays on your device. Save concise, useful findings within your retention preferences.

HeapFile: Remove VS Code Connection removes the extension's configured connection; it keeps installed runtimes and HeapFile data. See data controls, privacy, and extension terms.