agent-memory: A Standalone Memory System for AI Coding Agents

Introduction

agent-memory is a standalone memory system specifically designed for AI coding agents. It tackles a fundamental challenge: agents often "forget" crucial context between different threads or sessions. Traditional methods, like grepping through notes, are inefficient because they rely on knowing the exact keywords and lack an always-in-context mechanism or navigational signals.

This innovative system resolves these issues with a robust four-layer pipeline: signal ? journal queue ? consolidation ? tiered memory filesystem. The ultimate goal is to ensure that your AI agent begins each new task or thread with highly relevant context already available in an AGENTS.md file, eliminating the need for manual searching.

Installation

You can integrate agent-memory into your projects using several methods:

As a Nix Flake

Add it to your flake.nix:

# flake.nix
{
  inputs.agent-memory.url = "github:axiomhq/agent-memory";
  
  outputs = { self, agent-memory, ... }: {
    # your config
  };
}

As a Git Submodule

Include it directly in your repository:

git submodule add https://github.com/axiomhq/agent-memory

Standalone

Clone the repository and install dependencies:

git clone https://github.com/axiomhq/agent-memory
cd agent-memory
bun install

Examples

The agent-memory CLI provides a set of commands to manage your agent's memory:

Capture a Journal Entry

Record new information from a session:

bun run src/cli/index.ts capture --title "learned xstate guards" --body "guards return boolean, not truthy" --tags "topic__xstate"

List Memory Entries

View existing memory entries:

bun run src/cli/index.ts list

Read an Entry

Access specific memory content (this also increments its usage counter):

bun run src/cli/index.ts read id__abc123

Run Consolidation

Process journal entries into structured knowledge:

bun run src/cli/index.ts consolidate

Run Defrag

Periodically reorganize and optimize memory:

bun run src/cli/index.ts defrag

Generate output-agents.md

Create a consolidated memory file for an organization:

bun run src/cli/index.ts generate-agents-md --org default

Health Check

Verify the system's status:

bun run src/cli/index.ts doctor

Why use agent-memory?

agent-memory was developed to overcome critical limitations found in simpler memory systems, such as flat folders of markdown files. These limitations include:

• Keyword-dependent retrieval: Memories are only accessible if you guess the exact keyword, making retrieval unreliable.
• No hot memory: There's no mechanism for always-in-context information, requiring explicit searching for everything.
• No progressive disclosure: Lack of navigational signals or tiered memory means all information is presented equally, without highlighting what's most relevant.

By implementing structured consolidation and tiered disclosure, agent-memory ensures your agent starts with immediate, relevant context, rather than relying on a search command. This significantly enhances the efficiency and effectiveness of AI coding agents.

Links

• Official GitHub Repository: axiomhq/agent-memory