Agents

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

1. Motivation

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:

ws.enable_extension("memory")
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

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:

Use hb.HeavenBase("task", preset="debug").
Use ws.to_mcp(profile="agent").
Use ws.to_mcp(profile="memory") when the task only needs note memory, or profile="memstate" when it needs versioned project keypaths.
Use hb.LLM(preset="chat", gateway="portkey", cache=False).
Keep GLM tool calls on native OpenAI JSON tools unless a provider-specific failure proves otherwise.
Use llm.spec.engine.apply(llm.spec, profile="print") for redacted route inspection before live calls.

Summary

Workspaces own durable Agent data and memory rows.
MCP profiles keep the Tool surface explicit.
LLM sessions hold runtime history without pretending it is persisted Agent state.

Further Exploration

Related resources:

First LLM - Presets, providers, gateways, and sessions
HeavenBase MCP - Workspace MCP serving
Prompt - Prompt rows, translations, and CLI

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

1. Motivation

2. Workspace Memory

3. Prompt Instructions

4. LLM Session with Tools

5. Agent Smoke Path

Summary

Further Exploration

​1. Motivation

​2. Workspace Memory

​3. Prompt Instructions

​4. LLM Session with Tools

​5. Agent Smoke Path

​Summary

​Further Exploration

1. Motivation

2. Workspace Memory

3. Prompt Instructions

4. LLM Session with Tools

5. Agent Smoke Path

Summary

Further Exploration