librefang-registry/plugins/README.md

Plugins Registry

Plugins extend agent behavior through lifecycle hooks. They can inject memories into context before a turn, perform side-effect processing after a turn, or do both. Unlike skills (which add knowledge) or MCP servers (which add tools), plugins run as Python scripts that intercept the agent loop.

File Format

Each plugin lives in its own subdirectory:

plugins/
└── <plugin-name>/
    ├── plugin.toml          # required: plugin manifest
    ├── hooks/
    │   ├── ingest.py        # called on each incoming user message
    │   └── after_turn.py    # called after each completed agent turn
    └── requirements.txt     # Python dependencies (prefer stdlib-only)

plugin.toml format

name = "episodic-memory"         # must match directory name
version = "0.1.0"
description = "Episode-based memory segmentation and recall for cross-conversation context continuity"
author = "librefang"

[hooks]
ingest = "hooks/ingest.py"       # optional
after_turn = "hooks/after_turn.py" # optional

[i18n.zh]
name = "情景记忆"
description = "基于情景的记忆分段与召回，实现跨会话的上下文延续。"

Hook Protocol

Hooks communicate with the agent runtime via stdin/stdout JSON lines.

ingest hook

Receives the incoming user message and returns zero or more memory objects to inject into the agent's context for this turn:

stdin:  {"type": "ingest", "agent_id": "abc123", "session_id": "...", "message": "user message text"}
stdout: {"type": "ingest_result", "memories": [{"content": "Relevant fact from earlier session"}]}

after_turn hook

Receives the full turn transcript after the agent responds. Used for persistence (saving summaries, updating profiles, appending logs):

stdin:  {"type": "after_turn", "agent_id": "abc123", "session_id": "...", "messages": [...]}
stdout: {"type": "ok"}

Installing and Using Plugins

# List all available plugins
librefang catalog plugins

# Install a plugin globally
librefang plugin install episodic-memory

# Enable a plugin for a specific agent
librefang plugin enable episodic-memory --agent coder

# Disable a plugin for an agent
librefang plugin disable episodic-memory --agent coder

# List plugins active for an agent
librefang plugin list --agent coder

Hands can also declare an allowed_plugins list in HAND.toml, which restricts which installed plugins are active within that hand.

All Plugins (12 total)

Name	Version	Hooks	Description
auto-summarizer	0.1.0	ingest, after_turn	Maintains a running conversation summary to help agents handle long conversations without losing context
context-decay	0.1.0	ingest, after_turn	Time-based memory decay with relevance scoring for natural context forgetting
conversation-logger	0.1.0	after_turn	Logs all conversations to JSONL files for auditing, analytics, and debugging
episodic-memory	0.1.0	ingest, after_turn	Episode-based memory segmentation and recall for cross-conversation context continuity
guardrails	0.1.0	ingest	Safety filter that detects potentially harmful content patterns and injects warnings into agent context
keyword-memory	0.1.0	ingest	Extracts keywords and named entities from user messages and returns them as contextual memories
mempalace-indexer	0.3.0	ingest, after_turn	Auto-indexes conversations into MemPalace and recalls relevant memories — no API keys, no cloud
sentiment-tracker	0.1.0	ingest	Analyzes user message sentiment and injects emotional context so agents can respond with appropriate tone
todo-tracker	0.1.0	ingest, after_turn	Detects action items and tasks mentioned in conversations, persists them, and recalls them as context
topic-memory	0.1.0	ingest, after_turn	Topic-aware memory recall with keyword clustering for cross-conversation context
user-profile	0.1.0	ingest, after_turn	Persistent user profiling from conversation patterns for personalized agent responses

Note: the guardrails and mempalace-indexer plugins have no after_turn hook; conversation-logger has no ingest hook.

Hook Execution Order

For each agent turn, the runtime executes hooks in this order:

1. All ingest hooks run (in plugin installation order) — memories are collected and merged
2. Agent turn executes with the injected context
3. All after_turn hooks run (in plugin installation order)

Adding a New Plugin

1. Create plugins/<name>/plugin.toml with name, version, description, and [hooks].
2. Add hook scripts under hooks/ for each declared hook.
3. Keep hooks fast (under 500 ms) — they run synchronously on every turn.
4. List Python dependencies in requirements.txt; prefer standard library where possible.
5. Run python scripts/validate.py.
6. Submit a PR.

See CONTRIBUTING.md for the full guide.