Memory System Skill

Purpose

Implement a two-layer persistent memory system that maintains long-term knowledge (MEMORY.md) and short-term conversation history (HISTORY.md). This enables the AI to recall key facts across sessions while managing recent context.

Architecture

┌─────────────────┐     ┌──────────────────┐
│  MEMORY.md      │     │  HISTORY.md      │
│  (Long-term)    │     │  (Short-term)    │
│                 │     │                  │
│  - User prefs   │     │  - Recent convos │
│  - Project info │     │  - Decisions     │
│  - Key learnings│     │  - Actions taken │
│  - Facts        │     │  - Timestamps    │
└─────────────────┘     └──────────────────┘
       ▲                         ▲
       │   ┌───────────────┐     │
       └───┤   AI Agent    ├─────┘
           └───────────────┘

Capabilities

MEMORY.md (Long-term Storage)

• •Store user preferences and settings
• •Remember project-specific information
• •Keep key technical decisions and learnings
• •Maintain user facts (name, role, goals)
• •Store API keys, endpoints, and configuration (use carefully)

HISTORY.md (Short-term Context)

• •Record recent conversation summaries
• •Track decisions made and actions taken
• •Note what worked and what didn't
• •Maintain chronological context (last N sessions)

Dependencies

• •No external dependencies
• •Pure Markdown-based storage
• •Files are created on first use

Usage Examples

Working with MEMORY.md

<!-- MEMORY.md Example Structure -->
# User Memory

## Preferences
- Editor: VS Code
- Preferred languages: TypeScript, Python, Go
- Communication style: Concise, technical

## Project Context
- Current project: nanobot-oss
- Tech stack: Node.js, TypeScript
- Key directories:
  - `/src` - Source code
  - `/skills` - Skill definitions

## Technical Decisions
- Using pnpm for package management
- Prettier + ESLint for linting
- Vitest for testing

## User Facts
- Name: Alice
- Role: Senior Developer
- Focus: Developer tooling

Working with HISTORY.md

<!-- HISTORY.md Example Structure -->
# Conversation History

## 2026-02-13 14:30
**Task**: Create example skills for documentation
**Actions**:
- Created github/SKILL.md
- Created memory/SKILL.md
- Created tmux/SKILL.md
**Decisions**: Used consistent template across all skills
**Notes**: Skills should be practical and copy-paste ready

## 2026-02-13 10:15
**Task**: Debug failing test in parser module
**Actions**:
- Investigated tokenizer edge case
- Fixed regex pattern for multiline strings
- Added 3 new test cases
**Decisions**: Keep regex simple, validate with tests
**Outcome**: All tests passing

Best Practices

MEMORY.md Guidelines

1. •Keep it organized: Use clear headings and sections
2. •Be specific: Store concrete facts, not vague statements
3. •Update regularly: Add new learnings as they occur
4. •Review periodically: Clean up outdated information
5. •Structure for parsing: Use consistent formatting

Example format:

## Section Name
- **Key**: Value
- **Key**: Value with details

HISTORY.md Guidelines

1. •Timestamp every entry: Use ISO 8601 format
2. •Summarize, don't transcript: Capture essence, not full dialog
3. •Note decisions: What was decided and why
4. •Track outcomes: What happened as a result
5. •Rotate entries: Keep last 10-20 sessions, archive older

Example format:

## YYYY-MM-DD HH:MM
**Task**: Brief description
**Actions**:
- Action 1
- Action 2
**Decisions**: Key decisions made
**Outcome**: Result or status

Integration Pattern

Reading Memory

When starting a new session:

1. •

   Read MEMORY.md for context:

   markdown

   Use read_file to load user's long-term preferences and project knowledge.
   Pay attention to technical decisions, user preferences, and key facts.
   

2. •

   Read HISTORY.md for recent context:

   markdown

   Use read_file to load recent conversation history.
   Focus on last 1-2 entries to understand current task flow.
   

Updating Memory

After completing significant work:

1. •

   Update HISTORY.md:

   • •Append new entry with timestamp
   • •Summarize actions and decisions
   • •Remove oldest entries if too long
2. •

   Update MEMORY.md (when warranted):

   • •Add new technical decisions
   • •Update user preferences
   • •Record key learnings

Template Files

Empty MEMORY.md Template

# User Memory

## Preferences
<!-- User's preferred tools, styles, communication preferences -->

## Project Context
<!-- Current project name, structure, key files -->

## Technical Decisions
<!-- Important technical choices and rationale -->

## User Facts
<!-- Personalization info: name, role, goals -->

## API Keys & Config
<!-- Reference only - don't store actual secrets here -->

Empty HISTORY.md Template

# Conversation History

## YYYY-MM-DD HH:MM
**Task**: 
**Actions**:
- 
**Decisions**:
**Outcome**:

Configuration

Set memory file locations via environment variables:

export MEMORY_FILE="/home/user/.ai-memory/MEMORY.md"
export HISTORY_FILE="/home/user/.ai-memory/HISTORY.md"

Default locations (used if not set):

• •MEMORY.md in current workspace
• •HISTORY.md in current workspace

Tips

• •Balance detail: Too little = forgetful, too much = overwhelming
• •Be searchable: Use keywords that will help future searches
• •Link memories: Reference related decisions across files
• •Tag entries: Use labels like [CRITICAL], [EXPERIMENT], [LEARNED]

Security Note

⚠️ Never store actual secrets (passwords, API keys, tokens) in memory files:

• •Use references: "API key in ~/.config/app/key"
• •Environment variables: "Uses $OPENAI_API_KEY"
• •Config files: "Credentials in ~/.aws/credentials"