Memory

Project auto-memory, durable curated MEMORY.md / USER.md, write-approval, session search, and skill learner.

XibeCode has two complementary memory layers:

Project auto-memory — markdown files per project (facts, patterns, decisions).
Curated global memory — durable MEMORY.md + USER.md injected every session (bounded budget, frozen at session start).

Curated memory (global, durable)

Files:

~/.xibecode/memories/MEMORY.md   # agent notes: env, conventions, lessons
~/.xibecode/memories/USER.md     # who you are: name, role, preferences, style

How writes work

The agent uses the curated_memory tool (add / replace / remove, or an atomic operations batch).
On success: done=true and a note that the write is complete (do not repeat).
Success responses avoid dumping the full entry list (reduces re-save thrash). If the store is full, overflow errors return entries so the agent can consolidate.
Frozen snapshot: the system prompt loads MEMORY/USER once at session start. Mid-session disk writes are immediate for the next session, but the in-prompt snapshot stays fixed until a new session.

Messaging progress (Telegram / daemon)

When the agent saves curated memory you see progress like:

Saving MEMORY/USER…
Saved · MEMORY · usage% · N entries

Post-turn auto notes can surface the same way.

CLI write-approval (optional staging)

xibecode memory pending
xibecode memory approve <id>
xibecode memory reject <id>

What belongs in curated memory

Save	Skip
User preferences & corrections	Trivial / obvious facts
Stable environment & conventions	Raw data dumps, task TODOs
Durable procedures (short)	Full session logs → use `session_search`
	Reusable multi-step workflows → `save_skill`

Project auto-memory

Project-specific extraction and retrieval for coding conventions and past decisions.

How it works

Automatic Extraction: After conversation turns, notable facts/patterns can be stored as memory files
Context Retrieval: On session start, memories relevant to the prompt are ranked and injected
Dream Consolidation: Overlapping or stale entries are merged and pruned

Storage

~/.xibecode/projects/<sanitized-cwd>/memory/
  ├── 2026-05-03-api-patterns.md
  └── ...

Additionally, project-local notes:

<project-root>/.xibecode/memory.md

Both locations are scanned when listing or searching.

Memory file format

---
type: pattern
tags: [api, rest, express]
created: 2026-05-03T10:00:00Z
updated: 2026-05-03T10:00:00Z
relevance: 0.8
---

## API Pattern

All REST endpoints follow the controller-service-repository pattern.

Type	Description
`fact`	Factual observation about the codebase
`pattern`	Recurring convention
`decision`	Architecture / design decision
`correction`	User correction to remember
`preference`	How code should be written

CLI commands

# Project auto-memory
xc memory list
xc memory search "authentication flow"
xc memory dream
xc memory path

# Learning loop extras
xibecode memory sessions          # search past sessions
xibecode memory skills            # learned skills
xibecode memory pending           # staged curated writes (if enabled)

Ranking for search uses tag overlap, keyword match, and recency.

Chat commands (interactive TUI)

/memory list     Show project memories (up to 10; full list via CLI)
/memory dream    Run dream consolidation
/memory path     Print memory directory

Configuration

{
  "memory": {
    "enabled": true,
    "maxMemories": 100,
    "relevanceThreshold": 0.3,
    "dreamConsolidationInterval": 3600
  }
}

Setting	Description	Default
`memory.enabled`	Enable project auto-memory	`true`
`memory.maxMemories`	Max files before consolidation pressure	`100`
`memory.relevanceThreshold`	Min score for injection	`0.3`
`memory.dreamConsolidationInterval`	Seconds between auto dream	`3600`

Optional post-turn review uses XIBECODE_REVIEW_* env vars (cheap review model).

Session search & skills

Feature	Tool / path
Past conversations	`session_search` tool · `xibecode memory sessions`
Learned skills	`~/.xibecode/skills/learned/` · `save_skill` · `xibecode memory skills`
Progressive skills	`list_skills` then `view_skill`

Manual project memory

Write freely to .xibecode/memory.md in the project root — included in memory scans:

# Project Memory

## Conventions
- Always use pnpm
- Conventional commits
- TypeScript strict mode

Context injection

On a new session the agent:

Loads frozen curated MEMORY + USER (global)
Searches project memory files for relevance
Injects hits above threshold into context

You should not need to restate stable preferences every session.

Long chats trigger auto-compact (microcompact of old tool results, then a full handoff summary). That is separate from memory files — see Agent engine. Disable with autoCompactEnabled: false or XIBECODE_AUTO_COMPACT=0.

Next Steps

Agent engine — loop, auto-compact, learning
Settings — configure memory behavior
Xibe Daemon — memory progress on Telegram
Permissions — control tool execution