Knowledge Base and Memory

How the agent reads your knowledge base and writes durable memory back to Moxn

Slack conversations scroll away, and agent sessions are temporary. A Moxn agent treats your knowledge base as its long-term memory. It searches Moxn before it answers, and it writes decisions, findings, and sources back so the next conversation, and the next teammate, can start from them.

The knowledge base

Each agent is bound to one Moxn filesystem, chosen when you create the agent. The agent reads and writes it as its own identity, so the identity’s permissions decide what it can see and change. See Tools and permissions.

Everything the agent writes is ordinary Moxn content. Your team can read it, edit it, and search it in the web app, and other agents can reach it over MCP or the CLI.

The memory folder

The memory folder is where the agent keeps channel-specific working knowledge, such as the state of an ongoing investigation or notes on how this channel likes things done. It defaults to /agents/<agent-name>.

The memory folder is a location, not a boundary. The agent can use any content its identity can access. General knowledge, like a runbook or an architecture note, belongs where your team already keeps it, and the agent updates it there.

To limit what the agent can reach, scope its identity’s permissions, for example by making it a member of one filesystem only. The identity appears under Settings > Members, and filesystem access is set in each filesystem’s members list.

Durable memory instruction

Every agent starts with a system instruction maintained by Moxn, Use Moxn as durable memory. It tells the agent to:

• Search Moxn before answering, and read a document before updating it.
• Keep general knowledge in place and channel-specific working knowledge in the memory folder.
• Record decisions, findings, sources, and open questions, rather than transcripts.
• Distinguish established facts from hypotheses.
• Avoid duplicates by updating existing documents.
• Read back what it writes to confirm the change.
• Keep secrets out of Moxn.

Moxn maintains this instruction’s text. You can turn it off for an agent, for example when your own instructions define a different memory practice.

Your own instructions

Your instructions live in a knowledge-base document, not in a settings field. When you create an agent, Moxn seeds an Instructions document in its memory folder from a short template. The agent reads that document before every reply.

Edit it like any other document: in the editor, or with Claude Code or Codex through the edit tool. A change merged to the document’s main branch applies on the agent’s next message. There is nothing to deploy or restart.

Only two sections of the document are sent to the agent. Anything else, including the text above the first heading, is a note for people.

Section	When it applies	Use it for
## Instructions	Every reply	Standing rules: tone, scope, which documents to treat as canonical, when to stay quiet
## Starting context	Fresh conversations only, such as a new task thread	Background a new conversation should begin with, such as a project summary or current priorities

If the document has no ## Instructions heading, the whole body (minus ## Starting context) is treated as instructions. The Instructions section is limited to 32,000 characters and Starting context to 64,000; an over-limit document is refused rather than cut.

Reviewing a change before it goes live

Because instructions are a document, the usual review flow works. Edit on a branch, open a merge request, have a teammate approve, merge. Merging is what makes the change live.

For teams that want a release gate, the agent page’s Instructions version setting can pin the agent to the current main commit. A pinned agent keeps running that commit until someone pins a newer one; the agent page shows when main has moved ahead.

What the agent cannot do

The agent reads its instructions with its own identity, and Moxn caps that identity to read-only on the document. The agent cannot rewrite its own rules, even if someone in the channel asks it to. The agent page shows this cap and offers a one-click fix if it is ever removed.

If the document is deleted, moved out of the agent’s knowledge base, or becomes unreadable, the agent keeps using the last version it successfully read and the agent page flags the problem. An agent that has never read its document cannot run until it is fixed.

What lives where

Kept in	Lifetime
Slack	The full message history, as Slack retains it
Session context	Resumable until the session is closed; compacted as it grows
Sandbox files	Until the session is closed
Moxn	Durable, versioned, and searchable by your team and other agents