Zep memory plan

Zep is an agent memory platform. It stores user and application context as temporal knowledge graphs and returns prompt-ready memory context for agents.

For Bestie, Zep is useful later as a long-term memory layer. It should not replace local character files or the initial SQLite foundation.

Core concepts

User

One human account maps to one stable Zep user. Use a stable internal id, not a display name.

Example:

telegram_914093548

Thread

A thread is a conversation or session under a user.

For Bestie, use one long-running thread per chat surface or separate threads for major contexts.

Simple MVP recommendation:

user_id: telegram_914093548
thread_id: main_telegram_chat

Messages

Messages are conversation turns added to a thread. Zep can extract facts, entities, and relationships asynchronously.

Pattern:

1. User sends message.
2. Bestie retrieves relevant memory/context from Zep.
3. Bestie replies using persona plus memory context.
4. Bestie writes both user and assistant messages back to Zep.

Context block

Zep returns a prompt-ready context block. Bestie should place it below the persona prompt and above the live user message.

[System persona]
You are the bestie...

[Relevant memory from Zep]
<Zep context block here>

[Current user message]
...

Integration flow

Telegram/Web message received
  -> get or create Zep user
  -> get or create thread
  -> retrieve Zep memory/context for current message
  -> build prompt with persona + memory + current message
  -> call LLM
  -> send reply
  -> add user message + assistant reply to Zep thread

What to store

Good candidates:

• user’s name and preferred form of address
• relationship dynamic with the agent
• communication preferences
• ongoing projects
• emotional patterns and recurring topics
• recurring worries and goals
• personal principles and boundaries
• inside jokes
• important decisions

Ask before storing sensitive personal details, family/relationship details, health or mental health context, and secrets-adjacent identifiers.

Never store passwords, tokens, bank details, or one-off venting unless the user asks.

Zep vs local memory

Recommended path:

1. Build MVP with SQLite memory first.
2. Add Zep after the chat loop and memory controls work.
3. Keep a small local memory review UI/log even when using Zep.

Best architecture:

Persona + style examples = local files
Conversation state = local DB
Long-term user memory = Zep
Audit/debug logs = local files or DB

Do not outsource personality to Zep. Zep remembers facts and context; Bestie’s character is defined by local prompts and config.

Risks

• Over-remembering feels creepy.
• Bad retrieval makes replies weird or overconfident.
• Stale facts need temporal handling.
• Cost and lock-in need review before production reliance.
• Delete/export controls are mandatory for a real product.