Memory Agent Workshop

Give an Agent memory, but label the drawers before it starts collecting every paperclip.

1. Motivation

A useful Agent needs a bounded data surface, explicit tools, and durable notes. This workshop builds those pieces from HeavenBase primitives without requiring an API key or a separate orchestration runtime.

2. Reconstruct a Workspace

Create a version-2 manifest with one Preset, three requested extensions, and one user Entity:

import heavenbase as hb


manifest = hb.WorkspaceManifest.from_dict(
    {
        "kind": "heavenbase.workspace.manifest",
        "version": 2,
        "id": "memory-workshop",
        "construction": {"kind": "preset", "preset": "debug"},
        "extensions": ["toolkit", "agent", "memory"],
        "entities": [
            {
                "entity_id": "product",
                "fields": {
                    "object_id": {"type": "identifier", "pk": True},
                    "name": {"type": "short-text"},
                    "price": {"type": "float"},
                },
            }
        ],
    }
)

ws = manifest.open()

The replay registers a compatible durable workspace and leaves active selection unchanged. The manifest contains schema and construction, not row data.

3. Write and Query Data

ws.upsert(
    "product",
    {
        "object_id": "desk",
        "name": "Oak desk",
        "price": 89.0,
    },
)

rows = (
    ws.query("product")
    .where({"price": {"$lte": 100}})
    .select("name", "price")
    .execute()
    .rows()
)

The same workspace supports typed Python expressions, Mongo-style mappings, and query_json. Use explain() when the Agent or operator needs routing evidence.

4. Register a Scoped Profile

Profiles choose Tool groups, Entity visibility, Skill visibility, and serialization.

import heavenbase.ext as ext


profile = ext.profile_spec_from_mapping(
    "product-agent",
    {
        "extends": ["agent"],
        "entities": ["product"],
        "skills": ["*"],
        "serializer": "markdown",
    },
)

ext.register_profile(
    profile,
    replace=True,
    resolver=ws.module_resolver,
)

Profile registration writes through the Context-owned ModuleService. It does not create a second plugin registry.

5. Build the Agent Toolkit

ws.enable_extension("agent")
ws.enable_extension("memory")

toolkit = ws.to_mcp(profile="product-agent")
result = toolkit.run(
    "query",
    entity="product",
    spec={"select": ["name", "price"]},
)

The Toolkit is an in-memory object until explicitly registered in an application workspace. Its profile limits the Entity surface exposed to an Agent.

6. Add Flat Memory

memory = ws.to_mcp(profile="memory")

memory.run(
    "remember",
    key="setup",
    text="The product workspace uses the debug preset.",
    tags=["setup"],
)
hits = memory.run("search_memory", text="debug preset")

Memory entries are normal HeavenBase rows owned by the optional Memory extension. They are inspectable and queryable through the same workspace boundary.

7. Add Versioned Project State

memstate = ws.to_mcp(profile="memstate")

memstate.run(
    "memstate_set",
    project_id="demo",
    keypath="preferences.theme",
    value="dark",
)
memstate.run(
    "memstate_remember",
    project_id="demo",
    keypath="docs/readme",
    content="Explain the workspace boundary first.",
)
history = memstate.run(
    "memstate_history",
    project_id="demo",
    keypath="docs/readme",
)

Use flat Memory for searchable notes and Memstate for versioned project keypaths. Neither surface silently persists an LLMSession; LLM session persistence remains a separate boundary.

Summary

Version-2 manifests reconstruct a workspace shell without rows.
MCP profiles bound the Agent’s Tools, Entities, Skills, and output format.
Memory and Memstate persist through ordinary workspace Entities.
Toolkit registration and LLM session persistence remain explicit decisions.

Further Exploration

Related resources:

Workspace Manifests — Construction and replay rules
First MCP — Register and serve Toolkits
Agent Extension — Agent sessions, Skills, and recipes
MCP Toolkit Reference — Profiles and persistence

Introduction

Quickstart

Core Concepts

Developer

Utilities Toolbox

LLM

Agent Runtime

Community

Memory Agent Workshop

1. Motivation

2. Reconstruct a Workspace

3. Write and Query Data

4. Register a Scoped Profile

5. Build the Agent Toolkit

6. Add Flat Memory

7. Add Versioned Project State

Summary

Further Exploration

​1. Motivation

​2. Reconstruct a Workspace

​3. Write and Query Data

​4. Register a Scoped Profile

​5. Build the Agent Toolkit

​6. Add Flat Memory

​7. Add Versioned Project State

​Summary

​Further Exploration

1. Motivation

2. Reconstruct a Workspace

3. Write and Query Data

4. Register a Scoped Profile

5. Build the Agent Toolkit

6. Add Flat Memory

7. Add Versioned Project State

Summary

Further Exploration