Project Memory

muxd sessions start from zero — the agent forgets everything between sessions. Project Memory lets you persist structured facts so the agent remembers your conventions, architecture decisions, and gotchas across sessions.

How It Works

Facts are stored in a .muxd/memory.json file in your project root:

{
  "facts": {
    "auth": "JWT with refresh tokens, not sessions",
    "database": "SQLite with WAL mode, single writer",
    "test_patterns": "Table-driven tests, use t.Helper()"
  }
}

Simple flat key-value pairs. One file per project.

Reading (Automatic)

Every time the agent starts a turn, all stored facts are automatically injected into the system prompt. The agent sees them before you say anything — no tool call needed.

The system prompt includes a section like:

Project Memory:
auth: JWT with refresh tokens, not sessions
database: SQLite with WAL mode, single writer
test_patterns: Table-driven tests, use t.Helper()

Writing (Manual)

Facts are only saved when explicitly requested — either by you via /remember or by the agent calling the memory_write tool. Nothing is auto-saved.

Usage

The `/remember` Command

The fastest way to save facts from the TUI:

/remember auth JWT with refresh tokens
/remember database SQLite with WAL mode
/remember test_patterns Table-driven tests

Remove a fact:

/remember --remove auth

List all facts:

/remember

Agent Tools

The agent has two tools for memory:

Tool	Description
`memory_read`	Read all stored facts (also available via system prompt injection)
`memory_write`	Add, update, or remove a fact

You can ask the agent to remember things naturally:

"Remember that we use JWT with refresh tokens for auth"

The agent can call memory_write with action: "set" to persist the fact.

File Location

Memory is stored at .muxd/memory.json relative to your working directory. This means:

Each project gets its own memory file
You can commit .muxd/memory.json to share project context with your team
Or add .muxd/ to .gitignore to keep it local

Edge Cases

Situation	Behavior
No `.muxd/` directory	Created automatically on first write
No `memory.json` file	Agent sees no Project Memory section; reads return empty
Corrupt JSON	Read returns an error; you can delete and start fresh
Empty facts map	Project Memory section is omitted from system prompt
Sub-agents	Inherit the same memory — can read and write facts
Multiple sessions	All sessions in the same project directory share the same memory file

Hub Sync

When a node is registered with a hub, project memory is shared across all nodes:

Push -- when you save a fact (via /remember or the memory_write tool), it is pushed to the hub immediately.
Pull -- every 60 seconds, each node fetches the latest facts from the hub and merges any new or updated entries into its local memory.json.
TUI notification -- when new facts arrive from the hub, a blue [hub] synced N memory facts message appears in the TUI.

This means a fact saved on node A appears on node B within about a minute, without restarting either daemon. Local facts that already exist are not overwritten -- only new keys or changed values are merged.

No extra configuration is needed beyond the standard hub setup. If hub.url and hub.client_token are set, memory sync happens automatically.

Atomic Writes

Memory writes use a temp file + rename strategy to prevent corruption. The file is written to .muxd/memory.json.tmp first, then atomically renamed to .muxd/memory.json. This ensures the file is never left in a partial state.