memory

February 3, 2026 · View on GitHub

Long-term memory system for conversations with subcommands for memory management.

Commands

memory proxy

A middleware server that gives any OpenAI-compatible app long-term memory.

Usage

agent-cli memory proxy [OPTIONS]

Description

Acts as a proxy between your chat client and an LLM provider:

  1. Intercepts chat requests
  2. Retrieves relevant memories from a local vector database
  3. Injects memories into the system prompt
  4. Forwards the augmented request to the LLM
  5. Extracts new facts from the conversation and stores them

Key Features

  • Simple Markdown Files: Memories stored as human-readable Markdown
  • Automatic Version Control: Built-in Git integration
  • Lightweight & Local: Runs entirely on your machine
  • Proxy Middleware: Works with any OpenAI-compatible endpoint

Installation

pip install "agent-cli[memory]"
# or from repo
uv sync --extra memory

Examples

# With local LLM (Ollama) - uses default embedding model
agent-cli memory proxy \
  --memory-path ./memory_db \
  --openai-base-url http://localhost:11434/v1

# With local Ollama embedding model (requires: ollama pull nomic-embed-text)
agent-cli memory proxy \
  --memory-path ./memory_db \
  --openai-base-url http://localhost:11434/v1 \
  --embedding-model nomic-embed-text

# Use with agent-cli chat
agent-cli chat --openai-base-url http://localhost:8100/v1 --llm-provider openai

Options

Memory Configuration

OptionDefaultDescription
--memory-path./memory_dbDirectory for memory storage. Contains entries/ (Markdown files) and chroma/ (vector index). Created automatically if it doesn't exist.
--default-top-k5Number of relevant memories to inject into each request. Higher values provide more context but increase token usage.
--max-entries500Maximum entries per conversation before oldest are evicted. Summaries are preserved separately.
--mmr-lambda0.7MMR lambda (0-1): higher favors relevance, lower favors diversity.
--recency-weight0.2Weight for recency vs semantic relevance (0.0-1.0). At 0.2: 20% recency, 80% semantic similarity.
--score-threshold0.35Minimum semantic relevance threshold (0.0-1.0). Memories below this score are discarded to reduce noise.
--summarization/--no-summarizationtrueExtract facts and generate summaries after each turn using the LLM. Disable to only store raw conversation turns.
--git-versioning/--no-git-versioningtrueAuto-commit memory changes to git. Initializes a repo in --memory-path if needed. Provides full history of memory evolution.

LLM: OpenAI-compatible

OptionDefaultDescription
--openai-base-url-Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1).
--openai-api-key-Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable.

LLM Configuration

OptionDefaultDescription
--embedding-base-url-Base URL for embedding API. Falls back to --openai-base-url if not set. Useful when using different providers for chat vs embeddings.
--embedding-modeltext-embedding-3-smallEmbedding model to use for vectorization.

Server Configuration

OptionDefaultDescription
--host0.0.0.0Host/IP to bind API servers to.
--port8100Port to bind to

General Options

OptionDefaultDescription
--log-levelinfoSet logging level.
--config-Path to a TOML configuration file.
--print-argsfalsePrint the command line arguments, including variables taken from the configuration file.

memory add

Add memories directly to the store without LLM extraction.

Usage

agent-cli memory add [MEMORIES]... [OPTIONS]

Description

Useful for bulk imports or seeding memories. The memory proxy file watcher will auto-index new files.

Examples

# Add single memories as arguments
agent-cli memory add "User likes coffee" "User lives in Amsterdam"

# Read from JSON file
agent-cli memory add -f memories.json

# Read from stdin (plain text, one per line)
echo "User prefers dark mode" | agent-cli memory add -f -

# Read JSON from stdin
echo '["Fact one", "Fact two"]' | agent-cli memory add -f -

# Specify conversation ID
agent-cli memory add -c work "Project deadline is Friday"

Options

Options

OptionDefaultDescription
--file, -f-Read memories from file. Use '-' for stdin. Supports JSON array, JSON object with 'memories' key, or plain text (one per line).
--conversation-id, -cdefaultConversation namespace for these memories. Memories are retrieved per-conversation unless shared globally.
--memory-path./memory_dbDirectory for memory storage (same as memory proxy --memory-path).
--git-versioning/--no-git-versioningtrueAuto-commit changes to git for version history.

General Options

OptionDefaultDescription
--quiet, -qfalseSuppress console output from rich.
--config-Path to a TOML configuration file.
--print-argsfalsePrint the command line arguments, including variables taken from the configuration file.

File Format

Supports:

  • JSON array: ["fact 1", "fact 2"]
  • JSON object with memories key: {"memories": ["fact 1", "fact 2"]}
  • Plain text (one fact per line)

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Your Client   │────▶│  Memory Proxy   │────▶│   LLM Backend   │
│                 │◀────│  :8100          │◀────│                 │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                 │
                    ┌────────────┼────────────┐
                    │            │            │
           ┌────────▼───┐  ┌─────▼─────┐  ┌───▼───────┐
           │  ChromaDB  │  │ Markdown  │  │    Git    │
           │  (Vector)  │  │  (Files)  │  │ (Version) │
           └────────────┘  └───────────┘  └───────────┘

Memory Files

Stored as Markdown under {memory-path}/entries/<conversation_id>/:

entries/
  <conversation_id>/
    facts/
      <timestamp>__<uuid>.md
    turns/
      user/<timestamp>__<uuid>.md
      assistant/<timestamp>__<uuid>.md
    summaries/
      summary.md

See Memory System Architecture for the full schema and metadata format.