跳到主要内容

Memory System

The Viben agent memory system provides persistent, structured storage for agent knowledge and daily activities. This guide covers the memory architecture and management commands.

Memory Architecture​

Each agent has a memory/ directory with two types of files:

FilePurposeRead Timing
MEMORY.mdMain memory file with structured knowledgeEvery session start
YYYY-MM-DD.mdDaily logs (append-only)Today + yesterday at session start

Directory Structure​

~/.viben/agents/<agent-id>/memory/
|-- MEMORY.md            # Main memory file (structured knowledge)
|-- 2024-01-13.md        # Daily log (3 days ago)
|-- 2024-01-14.md        # Daily log (2 days ago)
|-- 2024-01-15.md        # Daily log (yesterday)
+-- 2024-01-16.md        # Daily log (today)

Main Memory (MEMORY.md)​

The main memory file contains structured, curated knowledge that the agent should always have access to.

Purpose​

  • Persistent context: Information that should be available across all sessions
  • Structured knowledge: Organized facts, preferences, and project context
  • Curated content: Manually maintained or agent-updated important information

Example Structure​

# Agent Memory

## User Preferences
- Prefers TypeScript over JavaScript
- Uses VS Code as primary editor
- Follows conventional commits format

## Project Context
- Current project: Viben CLI
- Main language: TypeScript
- Framework: Commander.js

## Important Decisions
- 2024-01-15: Decided to use YAML for configuration
- 2024-01-10: Chose sqlite for local storage

## Common Tasks
- Code review: Focus on type safety and error handling
- Commits: Use conventional commit format

## Notes
- API keys stored in environment variables
- Tests use vitest framework

When to Update MEMORY.md​

  • Add new user preferences discovered during sessions
  • Record important project decisions
  • Update project context when it changes
  • Remove outdated information

Daily Logs (YYYY-MM-DD.md)​

Daily logs are append-only files that capture session activities.

Purpose​

  • Session history: What was worked on during each session
  • Progress tracking: Tasks completed and pending
  • Context continuity: Helps agent remember recent work

Format​

# 2024-01-16

## 10:30 - Session started
- Working on feature X
- Discovered issue with Y

## 14:15 - Completed task
- Fixed bug in Z
- Updated documentation

## 17:00 - Session ended
- Next steps: review PR, deploy to staging

Automatic Reading​

At session start, the agent automatically reads:

  • MEMORY.md (always)
  • Today's daily log (if exists)
  • Yesterday's daily log (if exists)

This is controlled by the DAILY_LOG_DAYS setting in .agentrc:

# Read today + yesterday (default)
DAILY_LOG_DAYS=2

# Read only today
DAILY_LOG_DAYS=1

# Read today + 2 previous days
DAILY_LOG_DAYS=3

Memory Management Commands​

View Memory​

# View main memory
viben agent memory show -n <agent-id>

# View specific date
viben agent memory show -n <agent-id> --date 2024-01-16

# View all memory files
viben agent memory show -n <agent-id> --all

Example:

viben agent memory show -n my-agent

Output:

Memory: my-agent

MEMORY.md (2.3 KB, modified 2h ago)
----------------------------------------
# Agent Memory

## User Preferences
- Prefers TypeScript over JavaScript
...

Daily Logs:
  2024-01-16.md  1.1 KB  today
  2024-01-15.md  3.2 KB  yesterday
  2024-01-14.md  2.8 KB  2 days ago

Append to Daily Log​

Add content to today's daily log:

viben agent memory append -n <agent-id> "content to append"

Example:

viben agent memory append -n my-agent "## 14:30 - Code review completed
- Reviewed PR #123
- Found 3 issues, all resolved"

This appends to memory/2024-01-16.md (today's date).

Edit Main Memory​

Open the main memory file in your default editor:

viben agent memory edit -n <agent-id>

Example:

viben agent memory edit -n my-agent

This opens ~/.viben/agents/my-agent/memory/MEMORY.md in the editor configured via settings.editor or the EDITOR environment variable.

Edit Specific Date​

viben agent memory edit -n <agent-id> --date 2024-01-15

Memory Best Practices​

MEMORY.md Organization​

  1. Use clear sections: Divide content into logical sections
  2. Keep it concise: Focus on essential information
  3. Update regularly: Remove outdated information
  4. Use markdown: Leverage headings, lists, and formatting

Daily Logs​

  1. Timestamp entries: Start each entry with time
  2. Be specific: Include actionable details
  3. Note blockers: Record issues and solutions
  4. Plan next steps: End sessions with next actions

Memory Hygiene​

# Periodically clean old daily logs (keep last 30 days)
viben agent memory cleanup -n my-agent --keep-days 30

# Archive old logs
viben agent memory archive -n my-agent --before 2024-01-01

Memory Flow Diagram​

Session Start
     |
     v
+----------------+
| Load MEMORY.md |  <-- Always loaded
+----------------+
     |
     v
+------------------+
| Load Today's Log |  <-- If exists
+------------------+
     |
     v
+----------------------+
| Load Yesterday's Log |  <-- Based on DAILY_LOG_DAYS
+----------------------+
     |
     v
+----------------+
| Agent Context  |
| Ready          |
+----------------+
     |
     | (During session)
     v
+------------------+
| Append to       |  <-- Agent or user adds entries
| Today's Log     |
+------------------+
     |
     | (If needed)
     v
+----------------+
| Update         |  <-- Important discoveries
| MEMORY.md      |
+----------------+

Configuration​

In .agentrc​

# Memory files to load at startup
MEMORY_FILES="MEMORY.md"

# Number of daily logs to read (today + N-1 previous days)
DAILY_LOG_DAYS=2

In config.yaml​

memory:
  main_file: MEMORY.md
  daily_log_days: 2
  auto_cleanup: true
  cleanup_keep_days: 30

Troubleshooting​

Memory Not Loading​

# Check if memory files exist
ls -la ~/.viben/agents/my-agent/memory/

# Verify file permissions
chmod 644 ~/.viben/agents/my-agent/memory/*

Daily Log Not Created​

Daily logs are created automatically on first append. To create manually:

viben agent memory append -n my-agent "# $(date +%Y-%m-%d)

## Session started"

Memory Too Large​

If MEMORY.md becomes too large:

  1. Archive old sections to a separate file
  2. Summarize detailed content
  3. Move project-specific info to workspace config
# Check memory size
viben agent memory show -n my-agent --stats

Output:

Memory Stats: my-agent
  MEMORY.md: 15.2 KB (recommended: < 10 KB)
  Daily logs: 23 files, 45.6 KB total
  Total: 60.8 KB

Next Steps​