Otto memory

Otto’s memory system transforms it from an agent that starts fresh every session into a knowledgeable team member that remembers your environment, your conventions, and lessons learned from past interactions. Memory is stored locally as Markdown files split between your project repository and your home directory.

How memory works

Memory lives in two places: your project repository and your home directory.

your-project/                  # Astro project root
└── .astro/
    └── memory/                # Shared project memory (committed, team-visible)
        ├── MEMORY.md
        └── conventions.md
~/                             # Your home directory
└── .astro/
    └── memory/
        ├── MEMORY.md          # Local user memory (all projects, this computer)
        ├── preferences.md
        └── <project-slug>/    # Local project memory (this project, this computer)
            ├── MEMORY.md
            └── notes.md

Each location serves a different purpose:

• Shared project memory (.astro/memory/): Conventions, architecture decisions, and environment details that should travel with the project. Committed to your repository so the whole team picks them up.
• Local project memory (~/.astro/memory/<project-slug>/): Your personal notes for one specific project. Lives in your home directory and isn’t committed.
• Local user memory (~/.astro/memory/): Preferences and patterns that apply to every project you work on. Lives in your home directory and isn’t committed.

At the start of every session, Otto loads MEMORY.md from each location. Other .md files are indexed by name so Otto knows they exist, but they’re read on demand rather than loaded upfront.

How memories get created

Otto creates memory in several ways:

From the current conversation with /remember

Run /remember in an interactive session to have Otto review the conversation and generate memory files for the reusable learnings it identifies. Otto proposes the memories before writing them, and you approve or reject each one.

From history with /bootstrap

Run /bootstrap to seed shared project memory from your git history and available GitHub PR history (when the GitHub CLI is installed and authenticated). This is useful when you’re starting with Otto on an established project and want to capture existing team knowledge without building it up organically.

Manually

Platform teams can add Markdown files directly to .astro/memory/ to seed Otto with explicit constraints before organic memory accumulates. Upload files with conventions, approved operators, retry policies, and other standards, and add each file to MEMORY.md so Otto knows they exist.

For example:

.astro/memory/
  MEMORY.md             # Index of all memory files
  conventions.md        # Naming conventions, preferred patterns
  approved-operators.md # Operators the team has approved for use
  retry-policy.md       # Standard retry configuration

Autonomously during a session

Otto can also write memory on its own when it detects something worth retaining, without you running /remember or /bootstrap. This happens when Otto:

• Discovers a project convention not represented in the codebase.
• Learns important environment facts such as versions, connections, or team structure.
• Corrects a prior mistake and wants to avoid repeating it.

Memory file format

Each memory file is a Markdown file with the following structure:

1
# <Title>
2
3
### Source
4
user-interaction | debugging-session | customer-call | documentation | experiment | code-review
5
6
## Memory
7
<concise learning — the core knowledge>
8
9
## Context
10
<when and why this was discovered — optional>
11
12
## Evidence
13
<concrete instances — grows over time as the memory is reinforced>

The MEMORY.md file in each folder serves as an index. Otto reads it at the start of every session to understand what memory files are available, and adds entries for new memories as they’re created.

When Otto does not write memory

Otto avoids writing memory for:

• Information already in README.md, CLAUDE.md, or committed documentation.
• Ephemeral task state or in-progress work.
• Code patterns that are readable directly from source.

Memory and team collaboration

Because shared project memory lives in .astro/memory/ within your project repository, it follows your team’s standard Git workflow:

1. Otto creates or updates a memory file during a session.
2. You review the change in your Git diff.
3. You commit and push the change.
4. Other team members pull the update.
5. In their next Otto session, the new memory is loaded automatically.

Local project memory and local user memory are scoped to you and aren’t shared with the team.