Sinapsis Chat History

Sinapsis templates for persistent chat history in chatbot workflows.

🐍 Installation • 🚀 Features • 📚 Usage example • 📙 Documentation • 🔍 License

The sinapsis-chat-history package provides templates for fetching, trimming, saving, deleting, and resetting persistent chat history associated with LLMConversationPacket conversations. It supports SQLite by default, plus optional PostgreSQL-compatible backends such as PostgreSQL and Supabase through the postgres extra.

🐍 Installation

Install using your preferred package manager. We strongly recommend using uv.

Install the base package:

uv pip install sinapsis-chat-history --extra-index-url https://pypi.sinapsis.tech

Or with raw pip:

pip install sinapsis-chat-history --extra-index-url https://pypi.sinapsis.tech

[!IMPORTANT] The base installation includes the sqlite provider. PostgreSQL and Supabase require the optional postgres extra:

uv pip install sinapsis-chat-history[postgres] --extra-index-url https://pypi.sinapsis.tech

all installs every optional dependency exposed by the package:

uv pip install sinapsis-chat-history[all] --extra-index-url https://pypi.sinapsis.tech

ChatHistoryTrim requires the optional trim extra:

uv pip install sinapsis-chat-history[trim] --extra-index-url https://pypi.sinapsis.tech

🚀 Features

Templates Supported

• ChatHistoryFetch: Loads stored messages into LLMConversationPacket.messages.
• ChatHistoryTrim: Trims fetched history to fit a tokenizer-based prompt budget before the LLM call.
• ChatHistorySave: Persists packet messages to the configured history backend.
• ChatHistoryDelete: Deletes stored messages using explicit user/session scopes.
• ChatHistoryReset: Clears the configured history table or storage scope.

Providers Supported

• sqlite: Default provider for local development and lightweight deployments.
• postgres: Shared relational backend for multi-user or concurrent workloads.
• supabase: PostgreSQL-compatible backend reachable through the Supabase database connection.

[!TIP] Use CLI command sinapsis info --all-template-names to show a list with all the available Template names installed with Sinapsis Chat History.

📚 Usage example

The following agent fetches stored chat history for the given user_id and session_id into LLMConversationPacket.messages, then trims older turns so the next LLM call stays within a target token budget.

agent:
  name: chat_history_fetch_messages
  description: Fetches stored chat history into the conversation packet messages.

templates:
  - template_name: InputTemplate
    class_name: InputTemplate
    attributes: {}

  - template_name: LLMConversationInput
    class_name: LLMConversationInput
    template_input: InputTemplate
    attributes:
      prompt: I'm thinking about taking Barnaby for a run, do you think I'm ready given my training?
      user_id: Sarah
      session_id: conv_1234

  - template_name: ChatHistoryFetch
    class_name: ChatHistoryFetch
    template_input: LLMConversationInput
    attributes:
      provider: sqlite
      db_config:
        db_path: "chat_history.sqlite3"
        table: "chat"
      fetch_args:
        limit: -1
        offset: 0
        order: asc
        order_by: created_at

  - template_name: ChatHistoryTrim
    class_name: ChatHistoryTrim
    template_input: ChatHistoryFetch
    attributes:
      tokenizer_model_name: "Qwen/Qwen3.5-9B"
      model_max_context: 16384
      reserved_output_tokens: 2048
      safety_margin_tokens: 256
      preserve_system_messages: true

📙 Documentation

Documentation for this and other sinapsis packages is available on the sinapsis website

Tutorials for different projects within sinapsis are available at sinapsis tutorials page

🔍 License

This project is licensed under the AGPLv3 license, which encourages open collaboration and sharing. For more details, please refer to the LICENSE file.

For commercial use, please refer to our official Sinapsis website for information on obtaining a commercial license.