Memory System

How memory works

Autohand uses a multi-level memory system that stores information in two locations:

Memories persist across sessions. When you start a new session, Autohand loads relevant memories from both levels and injects them into the agent's context. This gives the agent an awareness of how you work, what patterns your team follows, and what decisions have been made before.

Each memory is a short piece of text stored in a markdown file. The files are human-readable and easy to edit manually.

# Project memory structure
.autohand/
  memory/
    coding-style.md
    testing-conventions.md
    architecture-notes.md

# User memory structure
~/.autohand/
  memory/
    preferences.md
    editor-shortcuts.md
    commit-style.md

Storing memories

The simplest way to store a memory is with the # trigger during a conversation. Type # followed by the information you want Autohand to remember.

# Store a coding preference
# Always use TypeScript strict mode in this project

# Store an architecture decision
# We use the repository pattern for all database access

# Store a personal preference
# I prefer tabs over spaces, 4-width indentation

When you use the # trigger, Autohand processes the text and saves it as a memory. The agent determines whether the memory is project-specific or personal based on its content. A statement about TypeScript strict mode in "this project" goes to project memory. A statement about your personal indentation preference goes to user memory.

Similarity detection

Autohand checks new memories against existing ones using similarity matching. If you store a memory that is very close to something already saved, Autohand updates the existing memory instead of creating a duplicate.

# First time
# Always use ESLint with the Airbnb config
# -> Saved as new memory

# Later, you refine it
# Always use ESLint with the Airbnb config and Prettier integration
# -> Updates the existing memory instead of creating a duplicate

This keeps your memory store clean and avoids conflicting instructions. The similarity threshold is tuned to catch obvious duplicates while allowing genuinely different memories on related topics.

Automatic memory extraction

You do not have to manually tag every useful piece of information. When you use /clear or /new to end a conversation, Autohand reviews the session and automatically extracts memories from it.

The extraction process works like this:

1. Scan - The LLM reads through the conversation looking for preferences, decisions, corrections, and patterns
2. Classify - Each candidate memory is classified as either project-level or user-level based on context
3. Deduplicate - Candidates are compared against existing memories to avoid duplicates
4. Save - New memories are written to the appropriate directory

# During a session, you correct the agent:
> "No, don't use moment.js. We switched to date-fns in this project."

# When you run /clear, Autohand automatically extracts:
[memory] Saved project memory: "Use date-fns instead of moment.js for date handling"

# Next session, the agent already knows
> "Add a date formatter to the utils"
# Agent uses date-fns without being told

What gets extracted

The LLM looks for several categories of useful information:

• Corrections - When you tell the agent "don't do X, do Y instead"
• Preferences - Coding style, naming conventions, tool choices
• Architecture decisions - Database choices, API patterns, folder structure
• Project facts - Tech stack, deployment targets, environment details
• Workflow patterns - How you like to review code, commit messages, PR descriptions

Memory injection

At the start of each session, Autohand loads memories and injects them into the agent's system context. This happens before your first message, so the agent is already aware of your preferences from the moment you start typing.

The injection process is selective. Not every memory is loaded every time. Autohand picks memories that are relevant to the current project, the files you are working with, and the task at hand. This keeps the context window focused and avoids wasting tokens on irrelevant information.

# What the agent sees at session start (simplified)
[system] Project memories loaded:
  - Use date-fns instead of moment.js for date handling
  - Follow the repository pattern for database access
  - Run "bun test" not "npm test" in this project
  - API responses always use camelCase keys

[system] User memories loaded:
  - Prefer functional components over class components
  - Always add JSDoc comments to exported functions
  - Use conventional commits format for commit messages

Memories are loaded in order of relevance. If the context window is tight, lower-priority memories are dropped first. Project memories take precedence over user memories when they conflict, since project conventions apply to everyone working on the codebase.

Managing memories

Use the /memory command to view, edit, and delete stored memories.

View all memories

/memory

# Output:
# Project memories (.autohand/memory/):
#   1. Use date-fns instead of moment.js for date handling
#   2. Follow the repository pattern for database access
#   3. Run "bun test" for running tests
#   4. API responses always use camelCase keys
#
# User memories (~/.autohand/memory/):
#   1. Prefer functional components over class components
#   2. Always add JSDoc comments to exported functions
#   3. Use conventional commits format

Delete a memory

/memory delete 2

# Output:
# Deleted project memory: "Follow the repository pattern for database access"

Edit memories manually

Since memories are plain markdown files, you can also edit them directly with any text editor:

# Edit project memories
vim .autohand/memory/coding-style.md

# Edit user memories
vim ~/.autohand/memory/preferences.md

Each memory file can contain multiple memories, one per line or grouped under headings. The format is flexible. Autohand reads the full content of each file and treats it as context.

# coding-style.md

## TypeScript
- Always use strict mode
- Prefer interfaces over type aliases for object shapes
- Use zod for runtime validation

## Testing
- Use vitest for unit tests
- Use playwright for E2E tests
- Always test error paths, not just happy paths

## Naming
- Use camelCase for variables and functions
- Use PascalCase for components and classes
- Use UPPER_SNAKE_CASE for constants

Project vs user memory

Choosing the right level for a memory matters. Here is a practical guide for where different types of information belong.

Project memory

Project memory lives in .autohand/memory/ inside your repository. When committed to git, these memories are shared with everyone on your team. Any teammate running Autohand on the same repo gets the same project context.

Store these as project memories:

• Tech stack choices (framework, database, ORM)
• Code style rules that apply to the whole team
• Architecture patterns (API structure, folder layout)
• Testing conventions (test runner, coverage requirements)
• Build and deployment commands
• Library preferences (date-fns over moment, etc.)

# Good project memories
# We use Prisma for database access with PostgreSQL
# All API endpoints return JSON with camelCase keys
# Run "bun run build" to create a production build
# Tests live next to source files with .test.ts extension

User memory

User memory lives in ~/.autohand/memory/ on your machine. These memories are never committed to git and stay private to you. They apply across all your projects.

Store these as user memories:

• Personal coding style preferences
• Editor and tool preferences
• Commit message format you like
• How verbose you want the agent to be
• Your preferred language for comments
• Code review style

# Good user memories
# I prefer concise commit messages under 50 characters
# Always explain why, not just what, in code comments
# I like seeing the full diff before committing
# Use British English spelling in documentation

Settings sync

If you work across multiple machines, you can enable settings sync to keep your user memories consistent everywhere. When sync is turned on, user memories are encrypted and synced through your Autohand account.

# Enable settings sync
autohand config set sync.enabled true

# Check sync status
autohand config get sync

# Force a manual sync
autohand sync

Sync covers user memories, personal configuration, and custom keybindings. Project memories are not synced through this mechanism since they live in your git repository.

Sync uses end-to-end encryption. Your memories are encrypted on your machine before being uploaded. The Autohand servers never see the plaintext content of your memories.

Best practices

Keep memories concise and specific

Short, clear memories work better than long paragraphs. The agent parses them faster and is less likely to misinterpret the intent.

# Too vague
# We have some conventions around testing

# Specific and actionable
# Use vitest for unit tests. Each test file must have at least one test
# for the error case, not just the happy path.

Use project memory for team conventions

If a coding pattern applies to everyone on your team, put it in project memory and commit it. This saves every team member from having to teach the agent the same thing individually.

# Add and commit project memories
git add .autohand/memory/
git commit -m "Add team coding conventions to agent memory"

Review memories periodically

Over time, memories can become outdated as your project evolves. Run /memory every few weeks to check for memories that no longer apply. A memory that says "use Express" is wrong if you migrated to Fastify.

Organize with multiple files

Rather than putting everything in a single file, split memories into categories. This makes them easier to maintain and lets you share specific files with new team members.

.autohand/memory/
  coding-style.md       # Formatting, naming, patterns
  testing.md            # Test runner, coverage rules, test patterns
  architecture.md       # Folder structure, API design, database
  deployment.md         # Build commands, CI/CD, environments
  dependencies.md       # Library choices and version constraints

Let the agent learn naturally

You do not need to pre-populate memories before your first session. The automatic extraction system picks up patterns as you work. After a few sessions of correcting the agent ("use bun, not npm" or "we prefer arrow functions here"), those corrections become permanent memories.

The best memories come from real interactions. They capture the specific decisions and preferences that matter for your workflow, and they evolve as your project grows.

Importing memories from other tools

If you are switching from another coding CLI, Autohand can import your existing memories and instructions so you do not have to start from scratch. The /import command detects installed tools and pulls in memory data where available.

# Interactive import wizard
/import

# Import memory from a specific tool
/import claude
/import gemini

# Preview what will be imported without writing anything
/import --dry-run

What can be imported

Not every tool stores memory the same way. Here is what Autohand can pull in from each source:

Cursor, Cline, Continue, and Augment do not expose memory data in a format Autohand can import, though other categories like settings and MCP servers are supported.

Where imported memories land

Imported memories are stored in clearly labeled directories so they do not mix with your native Autohand memories:

# Claude project memories
~/.autohand/projects/{project}/imported-claude/
  CLAUDE.md
  memory/

# Gemini global memory
~/.autohand/memory/imported-gemini/
  GEMINI.md

After importing, you can review and reorganize these files. Autohand treats imported memories the same as native ones during session startup.

Frequently asked questions