Skip to main content
HeavenBase treats agent memory as a workspace, agent actions as MCP tools, and agent instructions as prompt rows.

​
1. Agent stack

A HeavenBase-backed agent usually has four parts:
  • hb.LLM for the model route, preset, provider, gateway, and cache policy
  • LLMSession from heavenbase.utils for multi-turn history and automatic tool loops
  • hb.Prompt and hb.fast_prompt_section for persisted, translated instructions
  • hb.HeavenBase(...).to_mcp(profile="agent") for workspace tools the model can inspect and mutate
This keeps the user interface small: the agent receives one prompt, one workspace MCP, and optional task-specific tools.
To persist agent history and recipes as workspace rows, enable the optional agent extension with ws.enable_extension("agent").

​
2. Workspace memory

Use a workspace preset instead of hand-writing backend config for first-run agents: 
import heavenbase as hb

ws = hb.HeavenBase("agent-memory", preset="debug")
workspace_mcp = ws.to_mcp(name="agent-memory-mcp", profile="agent").to_fastmcp()
The agent MCP profile intentionally exposes fewer tools than the full workspace toolkit. Start with it, then pass tools=[...] only when a specific agent needs a narrower allowlist. If the agent only needs persistent notes, start even smaller with the memory profile: 
memory_mcp = ws.to_mcp(name="agent-memory-notes", profile="memory").to_fastmcp()
The memory profile exposes remember, recall, search_memory, list_memory, and set_memory. It is useful for Memstate-style note storage while still keeping the data inside the same HeavenBase workspace. Use remember for summaries or decisions, recall/list_memory for exact retrieval and browsing, search_memory for fuzzy lookup, and set_memory for exact-key correction. History and delete stay out of this first-run profile until the application has a retention policy. If the agent needs versioned project memory, use the memstate profile: 
memstate_mcp = ws.to_mcp(name="agent-versioned-memory", profile="memstate").to_fastmcp()
The memstate profile exposes memstate_remember, memstate_set, memstate_get, memstate_search, memstate_history, and memstate_delete. It uses project.<project_id>.<keypath> rows and preserves history inside the HeavenBase workspace.

​
3. Prompt instructions

Register prompts in the same workspace so agent instructions travel with the task state: 
def system_prompt(task: str, *, tr=str) -> str:
    messages = hb.fast_prompt_section(
        system=tr("You are a task agent using HeavenBase as memory."),
        descriptions={"Task": task},
        instructions=["Inspect before mutating.", "Write structured results to the workspace."],
        tr=tr,
    )
    return messages[-1]["content"]


hb.Prompt(system_prompt, name="agent.system", ws=ws).register(ws=ws)
system = hb.Prompt.load("agent.system", ws=ws)(task="Summarize README.md")
Prompt names, versions, translations, and deletes are scoped to the workspace passed with ws=....

​
4. LLM session with tools

Attach workspace MCP and external MCP servers to one session: 
from heavenbase.utils import LLMSession

llm = hb.LLM(preset="chat", gateway="portkey", cache=False, temperature=0)
session = LLMSession(llm)
session.add_mcp(workspace_mcp, name="agent-memory-client")
session.add_mcp("http://127.0.0.1:7001/mcp", name="task-tools")

answer = session.send(
    "Inspect the task, write the result to HeavenBase, then answer.",
    system=system,
    max_tool_turns=10,
)
Tool-name collisions fail early so the model never sees ambiguous function names.

​
5. Agent smoke path

For a compact agent smoke test:
  1. Use hb.HeavenBase("task", preset="debug").
  2. Use ws.to_mcp(profile="agent").
  3. Use ws.to_mcp(profile="memory") when the task only needs note memory, or profile="memstate" when it needs versioned project keypaths.
  4. Use hb.LLM(preset="chat", gateway="portkey", cache=False).
  5. Keep GLM tool calls on native OpenAI JSON tools unless a provider-specific failure proves otherwise.
  6. Use hb.LLM(...).spec.materialize() for route inspection before live calls.

​
Further Exploration

Related resources: