Memory

Agent One uses a dual-layer memory system. Working memory is built-in and always available. Long-term memory is optional and provided by an external MCP server.

Working Memory

Built into the agent via SQLite (internal/agent/memory.go). Stores conversations, facts, and sessions.

Conversations (Sliding Window)

The agent maintains a sliding window of the last 10 messages (configurable). Only this window is sent to the LLM — not the full history. This keeps token costs low and context relevant.

When a message falls outside the window, it’s summarized and stored as a fact for future recall.

Facts (FTS5-Indexed)

Facts are key pieces of information the agent remembers between conversations. They’re stored in SQLite with FTS5 full-text search.

"Esteban prefers morning reports at 8am"
"Cronoss uses ClickUp for project management"
"Monthly purchase budget is $500"

Fact retrieval uses BM25 ranking with temporal decay:

score = BM25_score × e^(-λ × ageDays)

With a 30-day half-life, recent facts rank higher than old ones. This ensures the agent’s knowledge stays current without manual cleanup.

Facts are scoped by channel and user. A fact learned on WhatsApp from user A doesn’t leak to Telegram conversations with user B.

Sessions

A session groups related messages. Agent One creates a new session after 30 minutes of inactivity. When a session closes:

1. The conversation is summarized using the cheap model
2. The summary is stored as a fact
3. The conversation window resets

This means the agent retains the gist of old conversations without the token cost of replaying them.

Long-Term Memory (Engram)

Engram is an optional MCP server for cross-session recall. It stores architectural decisions, bug patterns, project conventions, and other high-value observations.

Setup

Engram is just another MCP server — 4 lines in config:

tools:
  mcp_servers:
    - name: engram
      command: "engram"
      args: []

No special code in Agent One. The MCP client discovers Engram’s tools automatically:

• mem_save — the LLM decides what’s worth remembering
• mem_search — semantic search across saved observations
• mem_timeline — progressive disclosure of recent memories

How it Works

Working memory (built-in)          Long-term memory (Engram MCP)
├── conversations table            ├── Observations with FTS5 search
├── facts table (FTS5-indexed)     ├── Timeline & progressive disclosure
├── sessions table                 └── Deduplication & soft delete
├── sliding window (last 10 msgs)
├── auto-summary on session close
└── scoped facts (channel, user)

The LLM decides when to save to long-term memory. It’s not automatic — the agent uses mem_save as a tool call when it encounters information worth persisting across sessions.

Tip

You don’t need Engram to get started. Working memory handles most use cases. Add Engram when you want the agent to remember decisions and patterns across weeks of usage.

Tool Call Loop Guard

To prevent the agent from getting stuck calling the same tool repeatedly, Agent One includes a loop guard:

• SHA256 dedup — identical tool calls (same name + same arguments) are detected
• Circuit breaker — after 3 identical calls in a row, the loop is broken and the agent moves on

This protects against runaway token usage from LLM hallucination loops.

Context Window Strategy

Agent One is aggressive about keeping context small:

Component	Budget
System prompt	< 300 tokens
Sliding window	Last 10 messages
Memory injection	Only relevant facts (keyword match)
Tool results	Summarized before adding to context

When a tool returns 50 ClickUp tasks, the agent sees a summary of the top 5. When the conversation grows long, old messages are summarized into facts. The goal: every token sent to the LLM earns its place.