Telegram Agent Memory

A file-first long-term memory library for Telegram bots.

You only need one supported LLM provider API key. No external database is required. This package is intentionally scoped to Telegram memory. External vector databases, graph databases, and generic memory-platform APIs are not part of the public product contract.

By default, stable member profile memory is shared across groups for the same userId, while recent daily memory stays group-specific.

The default product flow is simple:

• When a member sends a message, the LLM extracts what is worth remembering
• Long-term member state is written to PROFILE.md
• Recent events are written to memory/YYYY-MM-DD.md
• Before replying, context() always includes stable profile memory and automatically adds relevant recent memory

Install

npm install telegram-agent-memory

Minimal Setup

import { createTelegramMemory } from 'telegram-agent-memory';

const memory = await createTelegramMemory({
  apiKey: process.env.OPENAI_API_KEY!,
  whatToRemember: `
  Remember:
  - user preferences
  - ongoing plans
  - important status changes

  Ignore:
  - greetings
  - filler chat
  - one-off small talk
  `,
});

Store Memory

await memory.remember('I like coffee and usually work in Beijing.', {
  userId: 'tg_user_123',
  groupId: 'tg_group_456',
  username: 'alice',
});

By default, this creates files like:

.telegram-agent-memory/
  users/
    tg_user_123/
      PROFILE.md
      PROFILE.json
  groups/
    tg_group_456/
      members/
        tg_user_123/
          INDEX.json
          memory/
            2026-04-10.md
            2026-04-10.json

users/<userId>/PROFILE.* is the stable cross-group member profile. groups/<groupId>/members/<userId>/memory/* is recent group-specific memory.

INDEX.json is an internal local embedding index used for automatic recall. It is managed by the library and does not require any external database.

Build Prompt Context

This is the main read path.

context() automatically:

• includes stable member profile facts
• searches recent daily memory with the current message
• adds only relevant recent memory when it helps

const context = await memory.context('What should I know before replying?', {
  userId: 'tg_user_123',
  groupId: 'tg_group_456',
});

console.log(context.text);

The host bot does not need to decide when to use profile memory vs recent memory. The library decides that inside context().

Optional Recall

recall() still exists as a lower-level compatibility API if you want the ranked memory items directly.

Initialize From Environment

import { createTelegramMemoryFromEnv } from 'telegram-agent-memory';

const memory = await createTelegramMemoryFromEnv();

Common environment variables:

TELEGRAM_MEMORY_LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini
OPENAI_BASE_URL=
OPENAI_EMBEDDING_MODEL=text-embedding-3-small
OPENAI_HEADERS_JSON=
ANTHROPIC_API_KEY=
ANTHROPIC_MODEL=claude-3-5-haiku-latest
ANTHROPIC_BASE_URL=
ANTHROPIC_HEADERS_JSON=
TELEGRAM_MEMORY_DIR=./data/telegram-memory
TELEGRAM_MEMORY_POLICY=Remember user preferences and important status changes. Ignore filler chat.
TELEGRAM_MEMORY_RECENT_DAYS=3
TELEGRAM_MEMORY_MAX_PROFILE_FACTS=40
TELEGRAM_MEMORY_MAX_FACTS_PER_MESSAGE=8
TELEGRAM_MEMORY_SHARE_PROFILE_ACROSS_GROUPS=true

If TELEGRAM_MEMORY_DIR is not set, the default path is .telegram-agent-memory/ under the current working directory.

Public API

• createTelegramMemory(...)
• createTelegramMemoryFromEnv(...)
• TelegramMemory
• remember(...)
• context(...)
• recall(...) for lower-level access

Provider Compatibility

Built-in support today:

• OpenAI directly
• OpenAI-compatible APIs through OPENAI_BASE_URL
• OpenRouter-style setups, including optional headers through OPENAI_HEADERS_JSON, OPENROUTER_HTTP_REFERER, and OPENROUTER_APP_NAME
• Anthropic Claude through TELEGRAM_MEMORY_LLM_PROVIDER=anthropic plus ANTHROPIC_API_KEY

Embeddings are local by default. If you explicitly want OpenAI-compatible remote embeddings, set OPENAI_EMBEDDING_MODEL.

Evaluation

The repo includes fixture-based product tests for Telegram memory behavior:

• extraction into profile vs daily
• skip behavior for low-value messages
• automatic recent-memory recall inside context()
• user/group isolation
• English, Chinese, and mixed-language message coverage

Run them with:

npm run format:check
npm run test:telegram-memory
npm run lint
npm run release:check

Design Boundaries

• The library is file-first and does not use Qdrant, Neo4j, or another external vector database as part of the product path
• INDEX.json is an internal local semantic index, not a public storage abstraction
• The only supported public entrypoint is the Telegram-focused package root
• Historical generic-memory modules now live under legacy/ and are not part of the npm surface, the default tests, or the supported architecture
• The package is not designed for high-concurrency centralized shared storage or as a generic cross-channel memory backend
• Stable profile memory is shared across groups by default; set TELEGRAM_MEMORY_SHARE_PROFILE_ACROSS_GROUPS=false only if you explicitly want group-isolated profiles

See docs/ARCHITECTURE.md for the explicit product boundary. For local release hygiene, see docs/RELEASE.md.

License

MIT