Local inference, explicit project memory

Keep the roles clear

• Ollama: runs the model you install and select. Model downloads, disk space, memory, compute, and electricity are local requirements.
• HeapFile Project Memory: is a local-first workflow for notes you choose to save. It can preview selected project evidence and make one explicit question to a loopback Ollama model; it does not train the model or capture full chats.
• Your AI client: is a separate integration path. A client that supports Ollama and HeapFile MCP tools may use agent-memory tools, but that is distinct from the Project Memory desktop workflow. Ollama tool/function calling is not itself an MCP connection. Neither installing Ollama nor opening HeapFile automatically connects the two.

Only save concise notes you want to reuse, with their source or reason. Do not save credentials, whole conversations, or unrelated personal or employer information. Retrieved notes are sent to whichever inference provider your client is configured to use; local storage does not make a cloud model local.

Track 1: Local Project Memory with Ollama

Project Memory stores notes in the selected HeapFile profile and can pass a bounded preview to Ollama running on loopback. This desktop feature is separate from an AI client's MCP tools. Confirm Project Memory and its Ollama option are present in the HeapFile build available to your account before following the exercise; this guide does not claim every released build has been independently tested.

Prerequisites

• A supported operating system and enough disk, memory, and compute for the Ollama model you choose.
• Ollama installed, a model downloaded, and its local service available. Use Ollama's official download and current quickstart for your platform.
• HeapFile Desktop installed with Project Memory available, and the intended profile/data directory selected.
• Ollama installed locally if you want to use the explicit Ask Ollama action. No separate AI-client MCP configuration is required for the Project Memory desktop exercise.

Configure and verify

1. Install Ollama, then use its terminal commands to download and start a model that fits your machine. For example, ollama pull qwen3 followed by ollama run qwen3. This checks Ollama inference only.
2. In HeapFile Project Memory, create a disposable project and choose its retention period. Save one short, sourced test note and confirm the saved note appears in that project.
3. End the current session. Start a fresh HeapFile process, select the same profile/data directory, reopen the test project, and preview its context. Confirm the note and source appear in the preview before asking a question.
4. If the build offers the explicit Ask Ollama action, submit a question answerable only from the test note and confirm the response uses the previewed evidence. This one-call path uses local loopback inference; it does not invoke MCP tools or save the generated answer as a new fact.
5. Alternatively, export the visible Markdown handoff and inspect it before sharing. The export is a user-controlled copy; protect it like the source notes.

HeapFile does not automatically save transcripts. Project Memory notes are explicit and profile-local. An agent client's remember/prepare_work MCP workflow is a different memory surface; a successful MCP recall does not prove the Project Memory UI or its Ollama action worked. Ollama models and client settings change; check Ollama's tool-calling documentation and your chosen agent host's current support before relying on model-initiated tools.

Continue with the VS Code setup guide

Track 2: Memory Gateway pilot

Use this architecture when a separately deployed client needs a project-scoped HTTP memory interface. The pilot data plane returns sourced notes for that client to pass to Ollama or another inference provider you explicitly choose. Recall itself makes no model call.

This is not a hosted HeapFile Gateway service or a self-serve feature in the standard desktop download. A public Gateway installer or shared hosted endpoint is not available in this pilot. Contact HeapFile support before planning a deployment; do not install from a private source repository.

Integration boundary

• A deployment operator must provide a trusted Gateway runtime, select the intended HeapFile data profile, and create the project notes before a client can retrieve them.
• The versioned context endpoint is POST /v1/projects/<project_id>/context. Clients use a revocable, expiring bearer key bound to that project; the default permission is read-only. Saving or updating notes requires an explicit write grant.
• Keep the bearer key in the authorized application runtime or secret store, never in a URL, model prompt, browser storage, screenshot, or shared configuration. Pass only the selected project's sourced notes to the inference provider you intend to use.
• Before remote access, the operator must configure TLS, a private network boundary, edge rate limits, and a proxy that does not log bearer tokens, request bodies, or query strings. Keep the operator workbench on loopback and block direct access to the Gateway backend.

Browser cross-origin access is intentionally denied. Local loopback tests and a successful API response do not establish a supported hosted service or multi-tenant production deployment.

Pilot limits

• Project-scoped credentials restrict which project a client key can read; they do not provide organization SSO, user roles, or independent tenant encryption.
• Operators authorized for the local profile can manage every project. Project separation is not an operator-permission boundary.
• The pilot uses SQLite, not a clustered or encrypted-at-rest multi-tenant database. Protect the host with OS or device encryption and controlled access.
• Production or multi-tenant customer service is not established. Secret distribution and rotation, trusted deployment, backups, load testing, tenant isolation, audit retention, and incident response need separate implementation and review.
• Ollama inference remains your separately configured client/provider choice. The Gateway does not host models, run inference, authorize connectors, or make project notes safe to send to every provider.

Do not expose the pilot to the public internet or treat it as a production tenant service. See the HeapFile VS Code guide for the local MCP path.

Setup references

• HeapFile for VS Code — Desktop prerequisites, explicit MCP setup, saved-memory checks, and profile boundaries.
• Connect AI agents to HeapFile — client-specific MCP configuration and memory routine.
• Save and recall project context — a separate-session memory exercise.
• Trust and provider boundaries — what local storage does and does not mean for downstream model requests.