Guides

Opinionated guides for building with Threadline.

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.