Memory System

Overview

The memory system is organized into three distinct layers, each serving a different purpose:

All data lives in a single SQLite database with WAL mode enabled for concurrent reads. When sqlite-vec is available, the system performs hybrid search -- merging FTS5 keyword scores with vector cosine similarity for every query.

Knowledge Base

Source Files

The knowledge base is built from Markdown files in the workspace:

• MEMORY.md -- the root memory document (in workspace root)
• memory/*.md -- additional topic-specific memory files

Chunking Strategy

Documents are split into chunks for indexing with the following rules:

Incremental Indexing

Each chunk is hashed with SHA-256. On re-index, only chunks whose hash has changed are re-embedded and written. Unchanged chunks are skipped, keeping re-indexing fast.

Knowledge Sources

Every knowledge entry is tagged with a source field:

Embedding Providers

Configured via embedding.provider in config.yaml. Three options are available:

Local (default)

Runs entirely on-device using ONNX Runtime with the Xenova/all-MiniLM-L6-v2 model (384 dimensions). Zero API cost, works offline.

embedding:
  provider: "local"

Anthropic

Uses the Anthropic API for higher-quality embeddings. Requires a valid API key.

embedding:
  provider: "anthropic"

None

Disables vector search entirely. Only FTS5 keyword search is used. Simplest setup with no embedding dependencies.

embedding:
  provider: "none"

Embedding Cache

All computed embeddings are cached in the embedding_cache SQLite table to avoid redundant computation:

Hybrid Search

Every search query runs through a two-stage pipeline that merges vector and keyword results:

# For each query:
1. Vector search   -- cosine distance via sqlite-vec, top 30 candidates
2. Keyword search  -- FTS5 BM25 ranking
3. Score merge     -- final = 0.5 * vectorScore + 0.5 * keywordScore  (memory retrieval weights; tool selection uses 0.6/0.4)
4. Filter          -- discard results below 0.15 minimum score
5. Return          -- top 10 results

If vector search is unavailable (provider set to none, or sqlite-vec failed to load), the system falls back to keyword-only search using FTS5.

Telegram Feed

All incoming and outgoing Telegram messages are archived for later retrieval. The feed is stored across three tables:

When vector search is enabled, each message also gets an embedding stored alongside the text, allowing semantic search across the entire message archive.

Context Building (RAG)

When the agent processes an incoming message, context is assembled in four steps:

1. Fetch 10 most recent messages from the current chat
2. Hybrid search the Knowledge Base  -- top 5 chunks
3. Hybrid search the Telegram Feed   -- top 5 messages
4. Deduplicate results

The retrieved context is injected into the prompt in two labeled blocks:

[Relevant knowledge from memory]
  ... matched knowledge base chunks ...

[Relevant messages from Telegram feed]
  ... matched archived messages ...

Memory Tools

Two tools are exposed to the agent for explicit memory operations:

The agent can use these tools proactively -- for example, saving important user preferences to MEMORY.md so they persist across sessions.

Daily Logs

A daily log file is automatically created for each day the agent is active:

~/.teleton/workspace/memory/{YYYY-MM-DD}.md

Daily logs contain:

• Session notes and conversation summaries
• Memory flushes from session compaction
• Milestone events and notable interactions

System prompt inclusion (DM only): The logs for yesterday and today are automatically included in the system prompt, capped at 100 lines each. This gives the agent short-term memory across restarts. Group chats do not receive daily log context.

Session Memory

Before a session is compacted or a daily reset occurs, the system preserves key information:

1. An LLM generates a summary of the old session's conversation
2. The summary is saved to memory (either persistent MEMORY.md or the daily log)
3. The agent retains key facts, preferences, and context across session boundaries

This ensures continuity -- even after a context window reset, the agent remembers what matters.

Observation Masking

To save context window space, old tool results are compressed into a compact format:

[Tool: send_message - OK]
[Tool: search_messages - OK]
[Tool: get_balance - ERROR: insufficient funds]

Context Compaction

When the conversation grows too large, automatic compaction kicks in:

The compaction process:

1. AI generates a summary of the old conversation
2. Old messages are replaced with the summary
3. The last 20 messages are kept intact
4. A new session ID is assigned

Privacy

Memory context injection follows strict privacy boundaries:

This separation ensures that private notes, preferences, and personal information stored in memory are never exposed in group conversations.

Configuration

Memory-related settings in config.yaml:

embedding:
  provider: "local"    # "local" | "anthropic" | "none"
  model: null          # Override default model (optional)

storage:
  sessions_file: "~/.teleton/sessions.json"
  memory_file: "~/.teleton/memory.json"
  history_limit: 100

Database Tables

All data is stored in a single SQLite database (schema version 1.13.0). Key tables: