Persistent Memory - Mibyan Docs

Mibyan has bounded, curated memory that persists across sessions. This lets it remember your preferences, your projects, your environment, and things it has learned.

How It Works

Two files make up the agent’s memory:

File	Purpose	Char Limit
MEMORY.md	Agent’s personal notes — environment facts, conventions, things learned	2,200 chars (~800 tokens)
USER.md	User profile — your preferences, communication style, expectations	1,375 chars (~500 tokens)

Both are stored in ~/.mibyan/memories/ and are injected into the system prompt as a frozen snapshot at session start. The agent manages its own memory via the memory tool — it can add, replace, or remove entries.

One agent per Mibyan homeDon’t point two agent processes at the same Mibyan home directory. Memory writes are automatic and load back into the system prompt at session start, so two writers sharing one home will compound each other’s entries into state neither of them (nor you) authored. Memory is scoped per profile by design — give a second agent its own profile, and if they need shared memory, use an external memory provider instead.

Character limits keep memory focused. Memory does not auto-compact: when a write would exceed the limit, the memory tool returns an error instead of silently dropping entries. The agent then makes room itself — consolidating or removing entries in the same turn before retrying (see What Happens When Memory is Full). Note that replace is also bound by the limit: swapping an entry for a longer one can still overflow, so the new content must be shortened (or another entry removed) to fit.

How Memory Appears in the System Prompt

At the start of every session, memory entries are loaded from disk and rendered into the system prompt as a frozen block:

══════════════════════════════════════════════
MEMORY (your personal notes) [67% — 1,474/2,200 chars]
══════════════════════════════════════════════
User's project is a Rust web service at ~/code/myapi using Axum + SQLx
§
This machine runs Ubuntu 22.04, has Docker and Podman installed
§
User prefers concise responses, dislikes verbose explanations

The format includes:

A header showing which store (MEMORY or USER PROFILE)
Usage percentage and character counts so the agent knows capacity
Individual entries separated by § (section sign) delimiters
Entries can be multiline

Frozen snapshot pattern: The system prompt injection is captured once at session start and never changes mid-session. This is intentional — it preserves the LLM’s prefix cache for performance. When the agent adds/removes memory entries during a session, the changes are persisted to disk immediately but won’t appear in the system prompt until the next session starts. Tool responses always show the live state.

Memory Needs Session Boundaries

The whole memory system is built around the moment a session ends: MEMORY.md and USER.md carry the essentials into the next session, and session_search fills the gaps once the old context is gone. Inside a single session none of that machinery has a reason to run — everything important is still in the live context, so the agent rarely consults session_search and mostly compacts memory entries instead of curating them. This matters on messaging platforms (Telegram, Discord, etc.), where a chat is deliberately one continuous session that survives restarts, gateway crashes, and machine reboots. Shutting the machine down overnight does not end the session — the next message picks it up exactly where it left off. If you never reset, a chat can run for weeks as a single session: convenient, but it grows expensive (compaction runs repeatedly over an ever-longer history) and the learning loop of forget → recall from memory → search past sessions almost never gets to fire. Fresh memory entries also stay invisible to the running session because of the frozen snapshot above. Practice: run /new at natural boundaries — a finished task, a change of topic, the start of a day. Each boundary is when memory pays off: the agent re-reads the updated MEMORY.md/USER.md snapshot, starts from a cheap short context, and reaches for session_search when it actually needs history. On the CLI this mostly takes care of itself (every invocation is a new session); on gateways the boundary is yours to create.

Troubleshooting: “I told it to remember, and the next session it forgot”

The most common report looks like this: you tell the agent where something lives (an Obsidian vault, a project directory, a server), it answers “Done, I’ll remember that”, and a fresh session has no idea what you mean. Work through these in order — the first one explains the large majority of cases.

Check whether the write actually happened. Memory only persists when the model calls the memory tool; a sentence like “I’ve added that to my memory” is just text. Open the file and look for the entry:
cat ~/.mibyan/memories/MEMORY.md cat ~/.mibyan/memories/USER.md
If the fact is not there, the model claimed a save it never made. Small local models (roughly under 30B parameters) and models with weak tool-calling do this often — they produce the confirmation without the tool call. Ask explicitly (“use the memory tool to save the vault path /srv/vault”) and confirm the entry landed in the file. If it keeps happening, the fix is a stronger model for setup, not more instructions; once the entries exist, a smaller model reads them fine because they arrive in the system prompt.
Check the write wasn’t staged. With write_approval: true, writes outside the interactive CLI are held for review and never reach the file until approved — run /memory pending and /memory approve all. See Controlling memory writes.
Check you are reading the same memory you wrote. Memory is per profile: mibyan -p work (or work chat / work gateway start) reads ~/.mibyan/profiles/work/memories/, not ~/.mibyan/memories/. A CLI session in the default profile and a Telegram bot on another profile do not share notes. mibyan profile list shows what exists.
Check memory is enabled. memory.memory_enabled: false (or memory under agent.disabled_toolsets) removes the tool entirely — the model cannot save anything, whatever it says. See Configuration.
Remember the snapshot is frozen at session start. A fact saved in the current session is visible to the next session, not to another session that was already running. Start a new session (/new, or a fresh CLI invocation) after the write.

Two things that do not make the agent remember: variables in .env (those are credentials and settings, not memory) and facts mentioned in passing without asking for them to be saved. For a location the agent needs on every run of a recurring task, a skill is often the better home than a memory entry — it loads only when relevant and does not compete for the 2,200-character budget.

Memory Tool Actions

The agent uses the memory tool with these actions:

add — Add a new memory entry
replace — Replace an existing entry with updated content (uses substring matching via old_text)
remove — Remove an entry that’s no longer relevant (uses substring matching via old_text)

There is no read action — memory content is automatically injected into the system prompt at session start. The agent sees its memories as part of its conversation context.

Substring Matching

The replace and remove actions use short unique substring matching — you don’t need the full entry text. The old_text parameter just needs to be a unique substring that identifies exactly one entry:

# If memory contains "User prefers dark mode in all editors"
memory(action="replace", target="memory",
       old_text="dark mode",
       content="User prefers light mode in VS Code, dark mode in terminal")

If the substring matches multiple entries, an error is returned asking for a more specific match. replace overwrites the whole matched entry with content — old_text only locates the entry, it is not cut out and replaced. The new content must be the complete new entry, including every part of the old one you want to keep. (A whole-entry old_text equal to the entry itself is matched exactly and wins over substring matches.)

Two Targets Explained

`memory` — Agent’s Personal Notes

For information the agent needs to remember about the environment, workflows, and lessons learned:

Environment facts (OS, tools, project structure)
Project conventions and configuration
Tool quirks and workarounds discovered
Completed task diary entries
Skills and techniques that worked

`user` — User Profile

For information about the user’s identity, preferences, and communication style:

Name, role, timezone
Communication preferences (concise vs detailed, format preferences)
Pet peeves and things to avoid
Workflow habits
Technical skill level

What to Save vs Skip

Save These (Proactively)

The agent saves automatically — you don’t need to ask. It saves when it learns:

User preferences: “I prefer TypeScript over JavaScript” → save to user
Environment facts: “This server runs Debian 12 with PostgreSQL 16” → save to memory
Corrections: “Don’t use sudo for Docker commands, user is in docker group” → save to memory
Conventions: “Project uses tabs, 120-char line width, Google-style docstrings” → save to memory
Completed work: “Migrated database from MySQL to PostgreSQL on 2026-01-15” → save to memory
Explicit requests: “Remember that my API key rotation happens monthly” → save to memory

Skip These

Trivial/obvious info: “User asked about Python” — too vague to be useful
Easily re-discovered facts: “Python 3.12 supports f-string nesting” — can web search this
Raw data dumps: Large code blocks, log files, data tables — too big for memory
Session-specific ephemera: Temporary file paths, one-off debugging context
Information already in context files: SOUL.md and AGENTS.md content

Capacity Management

Memory has strict character limits to keep system prompts bounded:

Store	Limit	Typical entries
memory	2,200 chars	8-15 entries
user	1,375 chars	5-10 entries

What Happens When Memory is Full

When you try to add an entry that would exceed the limit, the tool returns an error:

{
  "success": false,
  "error": "Memory at 2,100/2,200 chars. Adding this entry (250 chars) would exceed the limit. Consolidate now: use 'replace' to merge overlapping entries into shorter ones or 'remove' stale or less important entries (see current_entries below), then retry this add — all in this turn.",
  "current_entries": ["..."],
  "usage": "2,100/2,200"
}

The agent should then:

Read the current entries (shown in the error response)
Identify entries that can be removed or consolidated
Use replace to merge related entries into shorter versions
Then add the new entry

Best practice: When memory is above 80% capacity (visible in the system prompt header), consolidate entries before adding new ones. For example, merge three separate “project uses X” entries into one comprehensive project description entry.

Practical Examples of Good Memory Entries

Compact, information-dense entries work best:

# Good: Packs multiple related facts
User runs macOS 14 Sonoma, uses Homebrew, has Docker Desktop and Podman. Shell: zsh with oh-my-zsh. Editor: VS Code with Vim keybindings.

# Good: Specific, actionable convention
Project ~/code/api uses Go 1.22, sqlc for DB queries, chi router. Run tests with 'make test'. CI via GitHub Actions.

# Good: Lesson learned with context
The staging server (10.0.1.50) needs SSH port 2222, not 22. Key is at ~/.ssh/staging_ed25519.

# Bad: Too vague
User has a project.

# Bad: Too verbose
On January 5th, 2026, the user asked me to look at their project which is
located at ~/code/api. I discovered it uses Go version 1.22 and...

Duplicate Prevention

The memory system automatically rejects exact duplicate entries. If you try to add content that already exists, it returns success with a “no duplicate added” message.

Security Scanning

Memory entries are scanned for injection and exfiltration patterns before being accepted, since they’re injected into the system prompt. Content matching threat patterns (prompt injection, credential exfiltration, SSH backdoors) or containing invisible Unicode characters is blocked.

Session Search

Beyond MEMORY.md and USER.md, the agent can search its past conversations using the session_search tool:

All CLI and messaging sessions are stored in SQLite (~/.mibyan/state.db) with FTS5 full-text search
Search queries return actual messages from the DB — no LLM summarization, no truncation
The agent can find things it discussed weeks ago, even if they’re not in its active memory
The agent can also scroll forward/backward inside any session it finds

mibyan sessions list    # Browse past sessions

See Session Search Tool for the three calling shapes (discovery / scroll / browse) and the response format.

session_search vs memory

Feature	Persistent Memory	Session Search
Capacity	~1,300 tokens total	Unlimited (all sessions)
Speed	Instant (in system prompt)	~20ms FTS5 query, ~1ms scroll
Cost	Token cost in every prompt	Free — no LLM calls
Use case	Key facts always available	Finding specific past conversations
Management	Manually curated by agent	Automatic — all sessions stored
Token cost	Fixed per session (~1,300 tokens)	On-demand (searched when needed)

Memory is for critical facts that should always be in context. Session search is for “did we discuss X last week?” queries where the agent needs to recall specifics from past conversations.

Learning Journey (`/journey`)

The learning journey is a timeline view of everything Mibyan has learned — saved skills and memory entries plotted over time (oldest at top, newest at bottom), with a playable “constellation” scrubber that replays the build-up. The same graph data drives three surfaces:

Classic CLI / standalone — mibyan journey (aliases: mibyan learning, mibyan memory-graph) renders the timeline in the terminal. Flags: --play animates the build-up (--fps to tune it), --width/--height override the render size, --no-color disables color, and --json dumps the raw graph payload.
TUI — /journey (aliases: /learning, /memory-graph) opens the timeline as an overlay.
Desktop app — /journey opens the Star Map / memory-graph panel, an interactive visual of the same nodes.

A skill appears on the timeline as soon as it has a learning signal: it was created in this profile (a /learn result or a foreground skill_manage create), created by the background review, or used at least once. Bundled skills and hand-written skills that have never been used stay out of the timeline. Beyond viewing, the journey is also where you prune and correct what Mibyan has learned:

Command	What it does
`mibyan journey list`	List node ids — skill names and `memory:<source>:<index>:<fingerprint>` ids for memory chunks (pass one back exactly as printed).
`mibyan journey delete <node> [-y]`	Delete a node. Skills are archived (restorable), memory chunks are removed. `-y` skips the confirmation.
`mibyan journey edit <node>`	Open the node’s content (a skill’s `SKILL.md` or the memory chunk) in `$EDITOR`.

The same list / delete <id> / edit <id> subcommands work from the in-chat /journey command on the CLI, and the desktop panel offers edit/delete on nodes directly.

Configuration

# In ~/.mibyan/config.yaml
memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # ~800 tokens
  user_char_limit: 1375     # ~500 tokens
  write_approval: false     # false = write freely (default) | true = require approval

Setting both memory_enabled and user_profile_enabled to false turns the built-in stores off completely: the memory tool is dropped from the schema and its guidance block is dropped from the system prompt, so the model is never told about a tool it cannot use. An external provider set via memory.provider (Hindsight, Mem0, Honcho, …) is unaffected and keeps its own tools — use this when you want a third-party memory backend instead of the built-in files. Listing memory under agent.disabled_toolsets is the heavier switch: it hides external provider tools too. With only memory_enabled: false (user profile still on), the tool stays — it backs the profile store — but the system prompt swaps the full memory guidance for a narrower profile-only block. The tool schema advertises only the user target, and direct or staged writes to disabled MEMORY.md are rejected. The inverse configuration advertises only memory and rejects USER.md writes.

Controlling memory writes (`write_approval`)

By default the agent saves memory freely — including from the background self-improvement review that runs after a turn. If you’d rather approve saves first, set memory.write_approval: true. It’s a simple on/off gate applied to both foreground turns and the background review:

`write_approval`	Behaviour
`false` (default)	Write freely — the gate is off (the pre-gate behaviour).
`true`	Require approval before anything is saved. In the interactive CLI, foreground writes prompt you inline (entries are small enough to read in full). Everywhere else — messaging platforms, scripts, and the background self-improvement review — writes are staged for review with `/memory pending`.

To turn memory off entirely (not just gate it), set both memory_enabled: false and user_profile_enabled: false. When both built-in stores are disabled, the built-in memory tool is automatically hidden.

Review staged writes from the CLI or any messaging platform:

/memory pending             # list staged memory writes (auto ones tagged [auto])
/memory approve <id>        # apply one (or 'all')
/memory reject <id>         # drop one (or 'all')
/memory approval on         # turn the gate on (or 'off') and persist it

This is the answer to “the agent saved a wrong assumption about me”: set write_approval: true, and every save — especially the unprompted background ones — waits for your yes/no before it ever enters your profile. A staged replace or remove (the background review stages these even with the gate off) records the full entry it targets, and /memory pending shows it. Approval applies to exactly that entry: if it changed after the write was staged, the write is refused and stays pending for you to reject. A replace/remove staged before this pinning existed has no verifiable target and is refused too: reject it and recreate the change. /memory approve lists the full text of every entry it overwrote or removed.

Background review notifications (`display.memory_notifications`)

After a turn, the background self-improvement review may quietly save a memory or update a skill. This is Mibyan’ consent-aware learning loop: repeated corrections and durable workflow lessons become compact memory entries or procedural skills, while write_approval can stage those writes for review before they affect future sessions. By default it surfaces a short 💾 Memory updated line in chat so you know it happened. Control how chatty that is:

display:
  memory_notifications: on    # off | on (default) | verbose

Value	Behaviour
`off`	No chat notification. The review still runs and still writes — you just don’t see a line for it.
`on` (default)	Generic line, e.g. `💾 Memory updated`, `💾 Skill 'foo' patched`.
`verbose`	Includes a compact preview of what changed, e.g. `💾 Memory ➕ User prefers terse replies` or a `"old" → "new"` skill diff snippet.

This only governs the gateway chat notification. The review itself, and writes to your memory/skill stores, are unaffected by this setting. Set it per-platform via display.platforms.<platform>.memory_notifications.

Successful skill batches name each applied operation in both on and verbose mode, including supporting-file writes/removals and skill deletion. Staged writes awaiting approval and rolled-back batches are not reported as completed changes. Batch summaries use the applied results rather than assuming requested writes ran.

Running the review on a cheaper model (`auxiliary.background_review`)

The review runs on your main chat model by default, replaying the conversation — which is already warm in the prompt cache, so it’s cheap cache reads. On an expensive main model you can run the review on a cheaper model instead:

auxiliary:
  background_review:
    provider: openrouter
    model: google/gemini-3-flash-preview   # auto (default) = main chat model

When you point it at a model different from your main one, the review runs there for substantially lower cost (~3–5× in benchmarks). Because a different model can’t reuse your main model’s prompt cache anyway, the fork automatically replays a compact digest of the conversation (recent turns verbatim + a summary of older ones) rather than the full transcript — minimizing what it writes to the new cache. Capture holds: in testing, memory capture was identical and skill capture near-identical to the main-model review. Leave it at auto (or set it to your main model) and nothing changes — the review keeps running on the main model with the full warm-cache replay.

Same-model review reasoning

A review using the same model as the parent always inherits the parent’s reasoning effort. Setting auxiliary.background_review.reasoning_effort does not override it, whether the route is auto or explicitly selects the parent provider/model. Reasoning settings, the system prompt, the full conversation snapshot, and tool definitions stay byte-identical to the parent at fork birth so the review can reuse its prompt-cache prefix. Changing only the review’s thinking level would break that parity. There is no independent-effort switch for same-model reviews. To reduce review work without changing the main conversation’s effort, adjust memory.nudge_interval / skills.creation_nudge_interval, disable automatic reviews as described below, or route reviews to a different model. A different-model route uses a digest and does not share the parent’s warm prefix; on that route auxiliary.background_review.reasoning_effort IS honored (unset = the routed provider’s default). A one-time warning is printed when the key is set but the review stays on the main model. These frequency and routing controls do not decouple same-model reasoning.

Disabling automatic reviews (`enabled`)

The review fork can burn a meaningful share of total tokens on busy hosts. Operators can disable it without zeroing nudge intervals:

auxiliary:
  background_review:
    enabled: true              # false = skip automatic post-turn forks

With enabled: false, automatic post-turn forks do not spawn; manual /refine still works.

Capping review cost (`max_input_tokens`)

The review loop replays the conversation on every provider request it makes, so a single review can multiply input tokens across its tool iterations. max_input_tokens caps the SUM of replayed input tokens for one review; the loop stops before crossing it. <= 0 means unlimited.

auxiliary:
  background_review:
    max_input_tokens: 48000  # <= 0 = unlimited

When the key is unset, the budget is derived from the review model’s resolved context window: 75% of the window, capped at 600,000 tokens — so it also binds on small local models (a 65,536-token model gets 49,152), where a fixed cloud-scale default would never bite. If the window cannot be resolved, a conservative 120,000-token fallback applies. Note the key lives under auxiliary:; a top-level background_review: block is not read. Fork usage is persisted in session_model_usage with task='background_review' and a completion line is written to agent.log (Background review complete: thread=bg-review calls=… in=… out=… result=…).

Allowing a narrowly scoped extra review tool (`extra_tools`)

Background review can use memory, skill-management, and read-only file tools by default. If a profile provides another tool that is safe for unattended review, opt it in by name:

auxiliary:
  background_review:
    extra_tools:
      - propose_shared_memory

The tool must already be available to the parent agent; this setting only adds it to the review fork’s runtime whitelist. It does not enable arbitrary tools, and tools not listed here remain denied. Keep the list narrow and prefer tools that stage a proposal for human review rather than applying external or destructive changes directly. The default is an empty list.

Local models: reviews wait for an idle GPU (`defer`)

On a cloud provider the review finishes in seconds and runs alongside whatever you do next. When the review’s runtime is the managed local llama-server (Settings → Local models), the same fork occupies the GPU your next prompt needs — for minutes on a large model — and sending a new prompt cancels it, discarding the learning. So on the managed local runtime, reviews are deferred by default: queued at turn end and executed once the machine has been quiet for a short settle window. Nothing about the review itself changes — same model, same full-transcript replay, same writes — only the execution moment moves.

auxiliary:
  background_review:
    defer: auto            # auto (default) | never
    defer_max_age_s: 1800  # run a queued review anyway after this long

Value	Behaviour
`auto` (default)	Reviews whose runtime resolves to the managed local server are queued and run at idle; every other runtime (cloud, external servers) spawns immediately as before.
`never`	Old behavior everywhere: spawn immediately at turn end, even on the managed local GPU.

Queued reviews coalesce per session (a newer turn’s snapshot replaces the older one — the review replays the whole conversation, so nothing is lost), a review preempted by a new prompt is re-queued instead of discarded, and a review that has waited longer than defer_max_age_s runs even if the machine never goes idle. Explicit /refine always runs immediately. The queue is in-memory: reviews still pending when the app exits are dropped, same as an in-flight fork would have been.

Controlling skill writes (`skills.write_approval`)

Skills use the same on/off gate, but the review UX differs because a SKILL.md is far too large to read in a chat bubble:

skills:
  write_approval: false     # false = write freely (default) | true = require approval

When write_approval: true, skill writes (create / edit / patch / write_file / delete) always stage regardless of origin. You review the one-line gist inline, but the full diff stays out-of-band:

/skills pending             # list staged skill writes + a one-line gist each
/skills diff <id>           # full unified diff (best viewed in CLI or dashboard)
/skills approve <id>        # apply it (or 'all')
/skills reject <id>         # drop it (or 'all')
/skills approval on         # turn the gate on (or 'off') and persist it

On a messaging platform, approve a skill from its gist + metadata, or open /skills diff on the CLI / dashboard / the staged file under ~/.mibyan/pending/skills/<id>.json when you want to read the whole change. Full details in Gating agent skill writes.

External Memory Providers

For deeper, persistent memory that goes beyond MEMORY.md and USER.md, Mibyan ships with 7 external memory provider plugins — Honcho, OpenViking, Mem0, Holographic, RetainDB, ByteRover, and Supermemory — and more, such as Hindsight, are available from the plugin catalog via mibyan plugins install <name>. External providers run alongside built-in memory (never replacing it) and add capabilities like knowledge graphs, semantic search, automatic fact extraction, and cross-session user modeling.

mibyan memory setup      # pick a provider and configure it
mibyan memory status     # check what's active

See the Memory Providers guide for full details on each provider, setup instructions, and comparison.

​How It Works

​How Memory Appears in the System Prompt

​Memory Needs Session Boundaries

​Troubleshooting: “I told it to remember, and the next session it forgot”

​Memory Tool Actions

​Substring Matching

​Two Targets Explained

​memory — Agent’s Personal Notes

​user — User Profile

​What to Save vs Skip

​Save These (Proactively)

​Skip These

​Capacity Management

​What Happens When Memory is Full

​Practical Examples of Good Memory Entries

​Duplicate Prevention

​Security Scanning

​Session Search

​session_search vs memory

​Learning Journey (/journey)

​Configuration

​Controlling memory writes (write_approval)

​Background review notifications (display.memory_notifications)

​Running the review on a cheaper model (auxiliary.background_review)

​Same-model review reasoning

​Disabling automatic reviews (enabled)

​Capping review cost (max_input_tokens)

​Allowing a narrowly scoped extra review tool (extra_tools)

​Local models: reviews wait for an idle GPU (defer)

​Controlling skill writes (skills.write_approval)

​External Memory Providers

How It Works

How Memory Appears in the System Prompt

Memory Needs Session Boundaries

Troubleshooting: “I told it to remember, and the next session it forgot”

Memory Tool Actions

Substring Matching

Two Targets Explained

`memory` — Agent’s Personal Notes

`user` — User Profile

What to Save vs Skip

Save These (Proactively)

Skip These

Capacity Management

What Happens When Memory is Full

Practical Examples of Good Memory Entries

Duplicate Prevention

Security Scanning

Session Search

session_search vs memory

Learning Journey (`/journey`)

Configuration

Controlling memory writes (`write_approval`)

Background review notifications (`display.memory_notifications`)

Running the review on a cheaper model (`auxiliary.background_review`)

Same-model review reasoning

Disabling automatic reviews (`enabled`)

Capping review cost (`max_input_tokens`)

Allowing a narrowly scoped extra review tool (`extra_tools`)

Local models: reviews wait for an idle GPU (`defer`)

Controlling skill writes (`skills.write_approval`)

External Memory Providers