Chat Memory

Chat Memory persists AI agent working context across sessions. When enabled, every tool call is automatically logged — no manual tool call needed. AI restarts sessions with full context from previous work, without re-searching from scratch.

Architecture

SAVE:
  entry → SQLite (sync, always works)
       └→ Ollama embed() → Qdrant (background, fire-and-forget)

LOAD (chronological):
  SQLite → all recent entries by time

LOAD (semantic):
  query → Ollama embed() → Qdrant search(top-K) → SQLite fetch by ID
  → only returns relevant entries, saves tokens

Auto-Track

When CHAT_MEMORY_ENABLED=true, these tools automatically logto chat memory. The AI agent doesn't need to call any additional tool.

chat_context Tool

The chat_context tool provides manual control over chat memory with 5 actions: save, load, ingest, clear, resource.

Save — Store a single message

chat_context(
  action: "save",
  project_name: "my-app",
  role: "assistant",
  content: "Decision: use JWT with refresh tokens for auth flow"
)

Ingest — Dump full conversation

Call once at session end to persist the entire conversation.

chat_context(
  action: "ingest",
  project_name: "my-app",
  title: "Fix login bug — June 2026",
  messages: [
    { role: "user",    content: "fix login bug in auth.ts" },
    { role: "assistant", content: "Found the bug in token validation..." },
    { role: "user",    content: "ok, push it" }
  ]
)

Load — Retrieve context

Chronological load — "what were we working on?"

chat_context(
  action: "load",
  project_name: "my-app",
  limit: 20,           // max entries (default 20)
  max_age_hours: 168   // only within 7 days (default 168)
)

Semantic load — "anything about auth rate limiting?"

chat_context(
  action: "load",
  project_name: "my-app",
  semantic_query: "auth rate limiting middleware",
  limit: 10
)

// Flow: embed query → Qdrant search → SQLite fetch by ID
// Only returns entries semantically similar to the query.
// Falls back to chronological if Ollama/Qdrant are unavailable.

Clear — Delete old entries

chat_context(
  action: "clear",
  project_name: "my-app",
  max_age_hours: 720,       // delete entries older than 30 days
  thread_id: "ct_abc123"    // optional — delete only from this thread
)

Resource: knowledge://context/{project}

AI clients automatically read this MCP resource on session startup. No tool call needed — previous context is immediately available.

// AI reads: knowledge://context/my-app
// Returns formatted summary:

## Chat Context for "my-app"

### Fix login bug (4 msgs, 1200 chars, updated 2026-06-16)
  👤 User: fix login bug in auth.ts
  🛠 system [tool: search]: [keyword] "auth module" → 5 results
  🤖 AI [tool: smart_context]: task="fix bug" → 3 files
  👤 User: ok, push it

Session Lifecycle

Recommended pattern for AI agents using Chat Memory:

Configuration

Env Vars

Minimal Setup

# Enable chat memory (SQLite-only — no Qdrant/Ollama needed for memory)
CHAT_MEMORY_ENABLED=true
CHAT_MEMORY_VECTOR_ENABLED=false

Full Setup (recommended)

# Enable with semantic search (requires Ollama + Qdrant)
CHAT_MEMORY_ENABLED=true
CHAT_MEMORY_VECTOR_ENABLED=true

Best Practices

1. Ingest at session end — dump entire conversation once, not after every message.
2. Use semantic search for specific topics — when looking for past discussions on a topic, use semantic_query to get only relevant entries.
3. Use chronological load for resuming — when resuming a session, use chronological load to see everything in order.
4. Clear periodically — clean up entries older than 7-30 days to keep the database lean.
5. Adjust thread TTL — set CHAT_MEMORY_THREAD_TTL_MS to match your work patterns (short sessions = lower TTL).
6. Let auto-track work — don't call chat_context during normal work; auto-track handles search and context calls automatically.

Storage Details