Memory and history

"Memory" covers four different things in Hubzoid. They are stored in different places, written by different people or processes, and reach the agent in different ways. Keeping them apart is what lets a Hub share knowledge across a team without mixing one person's conversation into another's.

Authored knowledgeCopy Anchor Link

Knowledge is the Hub's reference material: definitions, policies, thresholds and how your systems fit together. It lives in knowledge/ as Markdown, is reviewed like code, and changes when someone edits it. The system prompt lists each document's name and description, and the agent reads a document in full with read_knowledge(name) when it needs it.

read_knowledge and list_knowledge read the folder from disk on every call, so an edit is visible to the next tool call without a restart. See the Hub.

Conversation historyCopy Anchor Link

The bridge does not keep conversations. Each chat request carries the conversation so far, and the bridge flattens it into one prompt with [system], [user] and [assistant] sections. Where that history comes from depends on the surface:

History is separate per surface and per conversation. A question asked in Slack is not visible in the web chat, and one WhatsApp chat never sees another.

For WhatsApp and Telegram, Hubzoid keeps the thread itself because those platforms do not replay it. Only the visible answer is stored, without the thinking panel or tool entries. Two settings bound it:

Usage rows in hz_usage record the time, surface, person, chat id, model, tokens, estimated cost and duration of every turn. They never contain message content.

Workflow stateCopy Anchor Link

Scheduled work needs to remember what it has already done. That memory belongs to the workflow and to the account a run acts as, not to a conversation. Every scheduled run acts as an ordinary account, chosen by run_as or the Hub's default, as described in workflows and schedules.

Code workflows use hub.state, a dictionary-like store in the operational database (hz_workflow_kv). Keys are scoped to the Hub, the workflow and the run's account, so two workflows never collide and the same workflow run for someone else starts empty. For state that is not about one person, hub.shared_state is shared by every account that runs the workflow. Keep personal data out of it. Values are JSON. Each assignment is committed at once and survives restarts and upgrades.

new = [b for b in breaches if not hub.state.get(f"explained:{b['service']}:{b['window_end']}")]
...
for b in new:
    hub.state[f"explained:{b['service']}:{b['window_end']}"] = report

A write to hub.state is its own commit, not a checkpointed step. If a run crashes after a write and is resumed, a read-modify-write such as a counter can be applied twice. Use per-item markers like the one above, which make a repeated run skip work it already finished. The workflow API covers the details.

Markdown tasks run each round in a fresh context, with no chat history. Continuity comes from a state file the task keeps for the run's account at <hub>/.hubzoid/schedule/<task>@<person>/state.json. Hubzoid's task preamble tells the agent to read it first and update it after every unit of work, so the next round or the next scheduled run resumes from it. Each run also writes a step-by-step log to the runs/ folder beside it. See markdown tasks.

State written before 1.0.1, in hub.state or in <hub>/.hubzoid/schedule/<task>/, is kept as it was and belongs to no account. Only a legacy Hub with no account configured still uses it.

The workflow engine separately checkpoints each completed step of a run, which is what lets an interrupted run resume without repeating finished steps. That is execution state, managed by the engine, not something your code reads.

Learned knowledgeCopy Anchor Link

Every Hub includes a remember(topic, content) tool that saves a durable learning as a knowledge document, so a correction made in chat reaches every later conversation. It is controlled rather than automatic.

Who can trigger itCopy Anchor Link

• The caller must hold the curator permission in the Hub, shown as Save shared knowledge in the Console. Grant it with hubzoid grant you@example.com curator my-hub on a Hub whose access Hubzoid manages. On a Hub with group-based access, membership of an Open WebUI group named curator counts instead.
• The caller must be on a surface allowed to reach restricted tools. By default, Slack, WhatsApp and Telegram callers, anonymous requests and hubzoid test are refused. HUBZOID_RESTRICTED_SURFACES changes the list.
• The tool's description tells the model to call it only when the person explicitly asks it to remember, save or note something, and never on its own initiative.
• In a Hub where nobody holds curator, every call is refused. A Hub tool named remember replaces the built-in one. It is not offered over MCP.

Every attempt, allowed or refused, is recorded in the access log with the person, surface and reason.

Where it writesCopy Anchor Link

remember writes one Markdown file per topic:

---
name: learned/billing-edge-cases
description: Learned knowledge about billing edge cases
learned_by: you@example.com
updated: '2026-09-25T09:41:07+00:00'
---

Credit notes issued after month end are booked in the month they are issued.

The document is readable through read_knowledge('learned/<slug>') and list_knowledge on the next call, for every person who uses the Hub. The knowledge menu in the chat agent's system prompt includes it after the next restart.

Review and correct itCopy Anchor Link

Learned documents are ordinary files in the Hub folder, so they go through the same review as the rest of the Hub:

1. Review changes. git status and git diff on knowledge/_learned/ show new and changed documents since the last commit. Commit what you keep.
2. Correct in chat. A curator asks the agent to remember the corrected fact. The document is replaced in full.
3. Correct by hand. Edit or delete knowledge/_learned/<slug>.md. The change is visible to the next read_knowledge call.
4. Undo the last write. Restore <slug>.md.bak over the document.
5. Audit who used it. hubzoid audit my-hub and the Console's Activity page list each remember decision with the person, surface and outcome.

Next stepsCopy Anchor Link

Read this page as Markdown