Guides

Opinionated guides for building with Threadline.

Use cases

• AI Coding Assistant — Remembers your stack, coding style, and ongoing projects. Never asks "what language are you using?" again.
• AI Customer Support Agent — Knows each customer's history, past issues, and product tier before they say a word. Support that actually feels personal.
• AI Tutor / Learning App — Tracks what the student has covered, where they struggled, and their learning pace. Every session builds on the last.
• AI Sales Assistant — Remembers every prospect — their role, deal stage, objections, and previous conversations. Your agent sells like a senior rep.
• AI Writing Tool — Learns your tone, style, and audience over time. Stops producing generic output from session one.
• AI Health & Fitness Coach — Remembers your goals, workout history, injuries, and preferences. Coaching that actually compounds.
• AI Voice Agent — Remembers how you like to be spoken to, your schedule, your recurring requests. Feels like a real assistant.
• AI Onboarding Flow — Picks up exactly where a new user left off — even days later. No repetition, no drop-off.
• AI Recruiting Assistant — Remembers every candidate — their skills, interview feedback, where they are in the pipeline. Never loses context between rounds.
• AI Personal Shopper — Knows your size, style, budget, and past purchases. Recommendations that get sharper every session.

Building your first memory-aware chatbot

1. Model first, memory second. Start with a simple chat endpoint that takes system + messages and returns a reply. Prove out tone and behaviour before wiring in Threadline.

2. Introduce tl.inject() at the system layer.

   Replace your static system prompt with:

   typescript

   const injected = await tl.inject(userId, basePrompt)

   Use injected as the system message you send to your model.

3. Update context on every turn.
   typescript

   await tl.update({ userId, userMessage, agentResponse })

   This keeps the user's context fresh and lets Threadline learn their style, tasks, and preferences over time.

4. Expose the trust dashboard. Link users directly to /account so they can see, edit, and delete their context. This is a critical trust signal.

Multi-agent context sharing

Threadline is designed for multi-agent ecosystems: multiple assistants, tools, and products sharing a single user context.

1. Give every agent its own API key. Each agent gets a separate key (and thus a separate agent_id). This keeps audit logs and rate limits clean.

2. Scope grants narrowly. When sharing context between agents, use specific scopes:

   typescript

   await tl.grant({
   userId,
   agentId: supportAgentId,
   scopes: ["communication_style", "ongoing_tasks"],
   })

   Your support agent doesn't need access to emotional state or unrelated preferences.

3. Visualize access for users. Use the trust dashboard (or your own UI) to show which agents currently have access, what scopes they have, and when access expires.

User privacy best practices

• Minimize stored data. Only write to preferences or emotional_state when it materially improves the experience.
• Avoid raw PII where possible. Store references (e.g. "my partner", "my manager") rather than full names or emails, unless absolutely necessary.
• Respect deletions immediately. When a user hits "Delete all my context", treat it as final. Clear caches, revoke grants, and make sure all downstream agents handle the absence of context gracefully.
• Audit everything. Threadline's audit log is meant for humans. Consider exposing a subset of it in your own UI so users can see when agents read or wrote their data.

Migrating from Zep to Threadline

If you're already using Zep or another memory API, migration typically looks like this:

1. Map your schema to Threadline.
   • Zep's summary / facts → Threadline communication_style, domain_expertise, preferences.
   • Zep's tasks / todos → Threadline ongoing_tasks.

2. Backfill via a one-time script. Write a script that:

   • Iterates over your users.
   • Reads their existing memory from Zep.
   • Calls Threadline's POST /api/context/update or uses the admin SDK to seed context objects.

3. Flip your runtime integration. Replace Zep's read/write calls with:

   typescript

   const prompt = await tl.inject(userId, basePrompt)
   await tl.update({ userId, userMessage, agentResponse })

4. Turn off writes to Zep, keep reads temporarily.

   For a short window, you may want to read from both systems while only writing to Threadline, then fully cut over once you're confident in the migration.