Plugins Overview¶

Plugins extend SimpleContext by hooking into the processing pipeline. They can intercept messages, modify context, inject data, log events, expose commands, and more.

How Plugins Work¶

Plugins are Python files with a class that inherits from BasePlugin. They attach to the pipeline via hooks:

User message saved    → on_message_saved()
Context being built   → on_context_build()
Before LLM call       → on_before_llm()
After LLM response    → on_after_llm()
Agent routed          → on_agent_routed()
Skill saved/deleted   → on_skill_saved() / on_skill_deleted()
Export/import         → on_export() / on_import()

Installation¶

Auto-scan (recommended)¶

Drop any .py plugin file into your plugins/ folder. SimpleContext auto-loads it on startup — no config changes needed:

cp my_plugin.py ./plugins/
# Restart your app → plugin is live

Via sc.use()¶

from my_plugin import MyPlugin

sc = SimpleContext("config.yaml")
sc.use(MyPlugin(config={"enabled": True, "option": "value"}))

With SimpleContext-Bot¶

# Install from official registry
simplecontext-bot plugins install vector-search

# Or drop manually
cp my_plugin.py ~/.simplecontext-bot/plugins/
simplecontext-bot start

Official Plugins¶

More plugins coming. See SimpleContext-Plugin for the registry.

Plugin Features¶

Persistent State¶

Plugins have access to self.state for persisting data across sessions:

def on_message_saved(self, user_id, role, content, tags, metadata):
    total = self.state.increment("total_messages")

State is stored in the same DB as SimpleContext (SQLite, Redis, or PostgreSQL).

App Commands¶

Plugins can declare commands that host applications (Telegram bot, Discord, CLI) auto-register:

app_commands = {
    "search": {
        "description": "Search memory by meaning",
        "usage":       "/search <query>",
        "handler":     "handle_search",
    }
}

async def handle_search(self, ctx: AppCommandContext) -> str:
    results = self._search(ctx.user_id, ctx.args_str)
    return format_results(results)

SimpleContext-Bot auto-registers these as Telegram commands with no code changes to the bot.

Dependencies¶

Declare which plugins must load before yours:

class MyPlugin(BasePlugin):
    name       = "my_plugin"
    depends_on = ["logger_plugin"]   # logger_plugin loads first

Plugin Registry¶

The SimpleContext-Plugin repo contains:

SimpleContext-Plugin/
├── official/           ← maintained by core team
│   └── plugin-vector-search/
├── community/          ← contributed by users
└── templates/
    └── plugin-starter/ ← copy this to start

Want to contribute a plugin? See Community Plugins.