Bootstrap and Persistent Memory

ChatCLI offers two complementary systems for customizing and contextualizing the agent: bootstrap files to define personality and rules, and persistent memory to maintain context across sessions.

The bootstrap and memory system is fully connected to the system prompt flow. Files are automatically loaded and injected into all interactions — in chat mode as well as in /agent and /coder modes.

Bootstrap Files

Bootstrap files are Markdown documents automatically loaded into the agent’s system prompt. They define who the assistant is, how it behaves, and which rules it should follow.

Supported Files

ChatCLI loads exactly 5 bootstrap files, in this order. All are optional — if they don’t exist, they are simply skipped:

File	Purpose	When to use
`AGENTS.md`	Sub-agent definitions and their roles	When you want to instruct the orchestrator about available agents and how to use them
`SOUL.md`	Assistant personality, tone and style	To define “who” the assistant is — how it speaks, thinks and behaves
`USER.md`	User preferences and project context	To inform the stack, conventions, preferred tools and project context
`IDENTITY.md`	Agent identity and capabilities	To define “what” the assistant is — name, capabilities, limitations
`RULES.md`	Explicit rules and restrictions	For strict guardrails — what it MUST and MUST NOT do

File names are exact and case-sensitive. ChatCLI only looks for AGENTS.md, SOUL.md, USER.md, IDENTITY.md, and RULES.md. Other names (like CLAUDE.md, README.md, etc.) are not loaded by the bootstrap system.

Loading Priority

Files are searched at two levels, with the workspace taking priority:

Workspace (./)

Project-specific configurations. Takes priority over global.

Global (~/.chatcli/)

User default configurations. Serves as a fallback when the file does not exist in the workspace.

If the same file exists at both levels, the workspace version prevails. Global files serve as fallback.

Detailed Examples

SOUL.md
USER.md
IDENTITY.md
RULES.md
AGENTS.md

Defines personality and tone. Place at ~/.chatcli/SOUL.md (global) or ./SOUL.md (project):

# Personality

You are a technical assistant specialized in software engineering.
Be concise and direct. Prefer practical examples over theoretical explanations.
When suggesting code, use best practices and tests.

# Tone

- Professional but approachable
- Prefer short and objective responses
- Use bullet points for lists
- Default language: English

Defines user and project context. Ideal for ./USER.md in the project directory:

# Project Context

- Stack: Go 1.25, gRPC, Kubernetes
- Database: PostgreSQL 16
- CI/CD: GitHub Actions
- Style: conventional commits, trunk-based development

# Preferences

- Always use tables for comparisons
- Prefer simple solutions without over-engineering
- Tests with idiomatic Go table-driven tests

Defines what the assistant is. Usually global at ~/.chatcli/IDENTITY.md:

# Identity

You are ChatCLI, an intelligent terminal assistant.

## Capabilities

- Code reading and editing via @coder plugin
- Shell command execution with user approval
- Log analysis and error diagnosis
- Git operations (status, diff, log, commit)

## Limitations

- You do NOT have internet access
- You CANNOT install packages without approval
- Your patches may fail if context has changed

Defines strict rules and guardrails. Can be global or per-project:

# Mandatory Rules

1. NEVER execute `rm -rf` without explicit confirmation
2. NEVER commit directly to the main branch
3. ALWAYS run tests after modifying code
4. ALWAYS use conventional commits (feat:, fix:, chore:)

# Security Restrictions

- Do not expose secrets, tokens or API keys in logs
- Do not modify files outside the project directory
- Do not execute commands with sudo

Defines sub-agents and their roles for the orchestrator:

# Custom Agents

## @devops
Infrastructure specialist for Docker, Kubernetes and CI/CD.
Use for deployment, monitoring and pipeline configuration tasks.

## @dba
PostgreSQL database specialist.
Use for queries, optimization, migrations and performance analysis.

## @security
Security auditor focused on OWASP Top 10.
Use for code review with focus on vulnerabilities.

Where to Place Files

# GLOBAL configuration (applies to all projects)
~/.chatcli/SOUL.md
~/.chatcli/IDENTITY.md
~/.chatcli/RULES.md
~/.chatcli/USER.md
~/.chatcli/AGENTS.md

# Per-PROJECT configuration (overrides global)
./SOUL.md          # In project root
./USER.md          # In project root
./RULES.md         # In project root (project rules)
./IDENTITY.md      # In project root (rare)
./AGENTS.md        # In project root (project agents)

Recommended strategy: SOUL.md and IDENTITY.md global (they’re about the assistant), USER.md and RULES.md per-project (they’re about the work context).

Smart Cache

Bootstrap files use mtime-based (modification time) caching:

On the first read, the content is cached in memory
Subsequent reads check if the mtime has changed
If the file was modified, the cache is automatically invalidated
IsStale() checks if any file has changed since the last load

Persistent Memory

The memory system maintains context across ChatCLI sessions, allowing the agent to “remember” facts, decisions, and patterns over time.

Storage Structure

All memory lives in ~/.chatcli/memory/:

~/.chatcli/memory/
|-- MEMORY.md              # Long-term memory (persistent facts)
|-- 202603/                # Daily notes for March 2026
|   |-- 20260301.md        # Notes from March 1st
|   |-- 20260302.md        # Notes from March 2nd
|   +-- 20260306.md        # Today's notes
+-- 202602/                # Daily notes for February 2026
    +-- 20260228.md        # Notes from February 28th

Daily notes are stored directly in YYYYMM/ subdirectories under ~/.chatcli/memory/, named as YYYYMMDD.md. There is no daily/ subdirectory.

MEMORY.md — Long-Term Memory

~/.chatcli/memory/MEMORY.md stores persistent facts the agent receives in every interaction:

# Architectural Decisions

- We use go-prompt v0.2.6 for interactive TUI
- Charmbracelet (glamour, lipgloss) only for styling, not for TUI
- Decoupled message bus via cli/bus for agent I/O

# Project Patterns

- json.Compact takes *bytes.Buffer, not *strings.Builder
- embed.FS always uses / in paths, never filepath.Join
- Stateful parsers > regex for XML with special attributes

Daily Notes — Temporal Journaling

Daily notes record what happened each day. ChatCLI automatically loads the last 3 notes into the prompt. Each entry gets an automatic timestamp (hour:minute):

## 14:32

Implemented fallback chain for LLM providers.
Added MCP support via stdio/SSE.
47 files changed, +4920 lines.

## 16:15

Decision: use init() auto-registration for providers in the registry.
Decision: cache_control:ephemeral for KV cache optimization on Anthropic.

How Memories Are Created

Memories are written automatically by a background worker. You don’t need to do anything.

Automatic Annotation (Background Memory Worker)

ChatCLI runs a background worker that periodically analyzes conversation history and uses the AI to extract annotations:

After each AI response (in any mode: chat, agent, coder), the worker is nudged
If there are 4+ new messages since the last extraction and at least 2 minutes since the last run, the worker fires
The worker sends the new messages to the AI with a structured extraction prompt
The AI returns two blocks: DAILY (what was done) and LONGTERM (new facts to remember)
Results are automatically saved to MEMORY.md and the daily note
A subtle ⟳ updating memory... indicator briefly appears (only when the prompt is idle)

The worker also runs periodically every 3 minutes, capturing annotations even during long agent/coder sessions.

The process is completely transparent — you don’t need to intervene. The AI decides on its own what’s important to annotate. Facts already in MEMORY.md are not duplicated.

`/memory` Command — View and Load Notes

Use /memory to view and load annotations:

Subcommand	Description
`/memory` or `/memory today`	Show today’s notes
`/memory yesterday`	Show yesterday’s notes
`/memory 2026-03-04`	Show notes from a specific date
`/memory week`	Show notes from the last 7 days
`/memory longterm`	Show MEMORY.md content
`/memory list`	List all memory files
`/memory load <date>`	Load a day’s notes into the current conversation context

/memory load is especially useful for resuming work from previous days:

/memory load yesterday

This injects yesterday’s notes into the conversation, allowing the AI to continue where it left off.

What goes in MEMORY.md vs daily notes?

MEMORY.md: Stable and long-lasting facts — architectural decisions, project patterns, team conventions, confirmed preferences. Accumulates across many sessions.
Daily notes (YYYYMM/YYYYMMDD.md): Temporal and specific records — what was done that day, errors found, files modified, tasks in progress.

Can I edit memories manually?

Yes! The files are plain Markdown — edit with any editor:

# Edit long-term memory
vim ~/.chatcli/memory/MEMORY.md

# Edit/create today's note
vim ~/.chatcli/memory/$(date +%Y%m)/$(date +%Y%m%d).md

# List all notes
find ~/.chatcli/memory/ -name "*.md" -type f | sort

Changes are picked up automatically on the next interaction (cache invalidates by mtime).

What information does the AI extract automatically?

The extraction worker asks the AI to identify:Daily notes (DAILY):

Files read, modified or created (with paths)
Commands executed and their outcomes
Errors encountered and how they were resolved
Tasks completed or in progress

Long-term memory (LONGTERM):

Architectural decisions made
Patterns or conventions discovered/established
User preferences expressed
Insights about project structure
Gotchas and technical constraints

If there’s nothing new to annotate, the AI simply skips.

What Gets Injected into the Prompt

The ContextBuilder assembles the following block and injects it as a system prompt prefix:

## AGENTS.md

[content of AGENTS.md]

---

## SOUL.md

[content of SOUL.md]

---

## USER.md

[content of USER.md]

---

## IDENTITY.md

[content of IDENTITY.md]

---

## RULES.md

[content of RULES.md]

---

# Memory

## Long-term Memory

[content of MEMORY.md]

## Recent Daily Notes

### 2026-03-04

[content of March 4th note]

### 2026-03-05

[content of March 5th note]

### 2026-03-06

[content of today's note]

Empty sections (missing files) are automatically omitted — only what exists is injected.

Configuration

Environment Variables
Via Helm Chart

CHATCLI_BOOTSTRAP_ENABLED=true
CHATCLI_BOOTSTRAP_DIR=/path/to/bootstrap/files
CHATCLI_MEMORY_ENABLED=true

# values.yaml
bootstrap:
  enabled: true
  definitions:
    SOUL.md: |
      You are a DevOps assistant...
    USER.md: |
      The user prefers Go...

memory:
  enabled: true
  # Uses the persistence PVC by default

The Helm chart creates ConfigMaps for bootstrap files and mounts them at /home/chatcli/.chatcli/bootstrap/. Memory uses the sessions PVC for persistence.

Context Injection Optimization (Prompt Caching)

ChatCLI optimizes token costs when contexts are attached using three complementary strategies:

Unified System Prompt with Cache Hints

Contexts attached via /context attach are injected as system prompt, not as user messages. This enables provider-level prompt caching:

Provider	Mechanism	Discount
Anthropic	`cache_control: ephemeral`	~90%
OpenAI	Automatic prompt caching	~50%
Google	Context caching API	Variable

The system prompt block contains:

Bootstrap (SOUL.md, USER.md, etc.)
Memory (MEMORY.md + daily notes)
Attached Contexts (new — previously injected as user messages)
K8s Watcher (if active)

Since the system prompt is identical across turns, the provider caches it and charges tokens at a discount.

Smart Compaction

Injected context messages (/memory load, summarized contexts) are automatically truncated during compaction (Level 1 — trimming). This prevents old reference context from consuming valuable token budget.

Token Visibility

The /context attached command now shows:

Estimated tokens per context
Total tokens per turn
Cache hints per provider
Warnings for oversized contexts

When running /context attach, the feedback includes the estimated cost per turn.

Best Practices

Global SOUL.md, per-project USER.md

Keep your preferred personality globally and technical context per project.

Keep MEMORY.md concise

Keep only stable and confirmed facts — not session-specific ones.

Daily notes for journaling

Use them to record decisions, solved problems, and temporal context.

Don't duplicate CLAUDE.md

If you already use CLAUDE.md or project instructions, avoid duplicating them in bootstrap.

Periodically review your memories and remove outdated ones to keep the context relevant.

Home

Getting Started

Core Concepts

Features

Support

Bootstrap and Persistent Memory

Bootstrap Files

Supported Files

Loading Priority

Detailed Examples

Where to Place Files

Smart Cache

Persistent Memory

Storage Structure

MEMORY.md — Long-Term Memory

Daily Notes — Temporal Journaling

How Memories Are Created

Automatic Annotation (Background Memory Worker)

`/memory` Command — View and Load Notes

What Gets Injected into the Prompt

Configuration

Context Injection Optimization (Prompt Caching)

Unified System Prompt with Cache Hints

Smart Compaction

Token Visibility

Best Practices

Global SOUL.md, per-project USER.md

Keep MEMORY.md concise

Daily notes for journaling

Don't duplicate CLAUDE.md

Next Steps

Conversation Control

Sessions

Home

Getting Started

Core Concepts

Features

Support

​Bootstrap Files

​Supported Files

​Loading Priority

​Detailed Examples

​Where to Place Files

​Smart Cache

​Persistent Memory

​Storage Structure

​MEMORY.md — Long-Term Memory

​Daily Notes — Temporal Journaling

​How Memories Are Created

​Automatic Annotation (Background Memory Worker)

​/memory Command — View and Load Notes

​What Gets Injected into the Prompt

​Configuration

​Context Injection Optimization (Prompt Caching)

​Unified System Prompt with Cache Hints

​Smart Compaction

​Token Visibility

​Best Practices

Global SOUL.md, per-project USER.md

Keep MEMORY.md concise

Daily notes for journaling

Don't duplicate CLAUDE.md

​Next Steps

Conversation Control

Sessions

Bootstrap Files

Supported Files

Loading Priority

Detailed Examples

Where to Place Files

Smart Cache

Persistent Memory

Storage Structure

MEMORY.md — Long-Term Memory

Daily Notes — Temporal Journaling

How Memories Are Created

Automatic Annotation (Background Memory Worker)

`/memory` Command — View and Load Notes

What Gets Injected into the Prompt

Configuration

Context Injection Optimization (Prompt Caching)

Unified System Prompt with Cache Hints

Smart Compaction

Token Visibility

Best Practices

Next Steps