Xây dựng Plugin cung cấp bộ nhớ

Các plugin của nhà cung cấp bộ nhớ cung cấp cho Hermes Agent kiến thức xuyên suốt, liên tục ngoài MEMORY.md và USER.md tích hợp sẵn. Hướng dẫn này bao gồm cách xây dựng một.

mẹo

Nhà cung cấp bộ nhớ là một trong hai loại plugin nhà cung cấp. Cái còn lại là Context Engine Plugins, thay thế trình nén ngữ cảnh tích hợp. Cả hai đều tuân theo cùng một mẫu: chọn một lần, điều khiển theo cấu hình, được quản lý thông qua `Hermes plugins

Cấu trúc thư mục

Mỗi nhà cung cấp bộ nhớ đều có `plugins/memory/<name/

` plugins/memory/my-provider/ ├── init.py # MemoryProvider implementation + register() entry point ├── plugin.YAML # Metadata (name, description, hooks) └── README.md # Setup instructions, config reference, tools

Nhà cung cấp bộ nhớ ABC

Plugin của bạn triển khai lớp cơ sở trừu tượng MemoryProvider từ `agent/memory_provider.py

from agent.memory_provider import MemoryProvider`class MyMemoryProvider(MemoryProvider):
    @property
    def name(self) -> str:
        return "my-provider"`def is_available(self) -> bool:
        """Check if this provider can activate. NO network calls."""
        return bool(os.environ.get("MY_API_KEY"))

def initialize(self, session_id: str, **kwargs) -> None:
        """Called once at agent startup.

kwargs always includes:
          Hermes_home (str): Active Hermes_HOME path. Use for storage.
        """
        self._API_key = os.environ.get("MY_API_KEY", "")
        self._session_id = session_id

# ... implement remaining methods

`

## Phương thức bắt buộc

### Vòng đời cốt lõi

| Phương pháp | Khi được gọi | Phải thực hiện? |
|--------|-------------|--------|
| 
`name
` (tài sản) | Luôn luôn | **Có** |
| 
`is_available()
` | Đại lý khởi tạo, trước khi kích hoạt | **Có** — không có cuộc gọi qua mạng |
| 
`initialize(session_id, **kwargs)
` | Khởi động đại lý | **Có** |
| 
`get_tool_schemas()
` | Sau khi init, để chèn công cụ | **Có** |
| 
`handle_tool_call(name, args)
` | Khi đại lý sử dụng công cụ của bạn | **Có** (nếu bạn có công cụ) |

### Cấu hình

| Phương pháp | Mục đích | Phải thực hiện? |
|--------|----------|--------|
| 
`get_config_schema()
` | Khai báo các trường cấu hình cho 
`Hermes memory setup
` | **Có** |
| 
`save_config(values, Hermes_home)
` | Viết cấu hình không bí mật vào vị trí gốc | **Có** (trừ khi chỉ có env-var) |

### Móc tùy chọn

| Phương pháp | Khi được gọi | Trường hợp sử dụng |
|--------|-------------|----------|
| 
`system_prompt_block()
` | Lắp ráp nhắc nhở hệ thống | Thông tin nhà cung cấp tĩnh |
| 
`prefetch(query)
` | Trước mỗi lệnh gọi API | Trả lại bối cảnh được thu hồi |
| 
`queue_prefetch(query)
` | Sau mỗi lượt | Làm ấm trước cho lượt tiếp theo |
| 
`sync_turn(user, assistant)
` | Sau mỗi lượt hoàn thành | Kiên trì trò chuyện |
| 
`on_session_end(messages)
` | Cuộc trò chuyện kết thúc | Chiết/xả lần cuối |
| 
`on_pre_compress(messages)
` | Trước khi nén ngữ cảnh | Lưu thông tin chi tiết trước khi loại bỏ |
| 
`on_memory_write(action, target, content)
` | Bộ nhớ tích hợp ghi | Phản ánh phần phụ trợ của bạn |
| 
`shutdown()
` | Quá trình thoát | Dọn dẹp kết nối |

## Lược đồ cấu hình``get_config_schema()
` trả về danh sách các bộ mô tả trường được 
`Hermes memory setup
` sử dụng:

`Python
def get_config_schema(self):
    return [
        &#123;
            "key": "API_key",
            "description": "My Provider API key",
            "secret": True,           # → written to .env
            "required": True,
            "env_var": "MY_API_KEY",   # explicit env var name
            "url": "https://my-provider.com/keys",  # where to get it
        &#125;,
        &#123;
            "key": "region",
            "description": "Server region",
            "default": "us-east",
            "choices": ["us-east", "eu-west", "ap-south"],
        &#125;,
        &#123;
            "key": "project",
            "description": "Project identifier",
            "default": "Hermes",
        &#125;,
    ]

`
``Các trường có 
`secret: True
` và 
`env_var
` sẽ chuyển đến 

.env

. Các trường không bí mật được chuyển tới 
`save_config()

.

:::tip[Minimal vs Full Schema]
Mọi trường trong 
`get_config_schema()
` đều được nhắc trong 
`Hermes memory setup

. Các nhà cung cấp có nhiều tùy chọn nên giữ lược đồ ở mức tối thiểu — chỉ bao gồm các trường mà người dùng **phải** định cấu hình (khóa API, thông tin xác thực bắt buộc). Ghi lại các cài đặt tùy chọn trong tham chiếu tệp cấu hình (ví dụ: 

$Hermes_HOME/myprovider.JSON

) thay vì nhắc tất cả chúng trong khi thiết lập. Điều này giúp trình hướng dẫn thiết lập nhanh chóng trong khi vẫn hỗ trợ cấu hình nâng cao. Hãy xem ví dụ về nhà cung cấp Supermemory — nó chỉ nhắc nhập khóa API; tất cả các tùy chọn khác đều có trong 
`supermemory.JSON

.

:::

## Lưu cấu hình

``` python
def save_config(self, values: dict, Hermes_home: str) -> None:
    """Write non-secret config to your native location."""
    import JSON
    from pathlib import Path
    config_path = Path(Hermes_home) / "my-provider.JSON"
    config_path.write_text(JSON.dumps(values, indent=2))

`
``Đối với các nhà cung cấp chỉ có env-var, hãy để mặc định no-op.

## Điểm vào plugin

`Python
def register(ctx) -> None:
    """Called by the memory plugin discovery system."""
    ctx.register_memory_provider(MyMemoryProvider())

`

## plugin.YAML

`YAML
name: my-provider
version: 1.0.0
description: "Short description of what this provider does."
hooks:

  - on_session_end    # list hooks you implement

`

## Hợp đồng luồng`**
`sync_turn()
` PHẢI không chặn.** Nếu phần phụ trợ của bạn có độ trễ (các lệnh gọi API, xử lý LLM), hãy chạy công việc trong một chuỗi daemon:

``` python
def sync_turn(self, user_content, assistant_content):
    def _sync():
        try:
            self._API.ingest(user_content, assistant_content)
        except Exception as e:
            logger.warning("Sync failed: %s", e)

if self._sync_thread and self._sync_thread.is_alive():
        self._sync_thread.join(timeout=5.0)
    self._sync_thread = threading.Thread(target=_sync, daemon=True)
    self._sync_thread.start()

`

## Cách ly hồ sơ

Tất cả các đường dẫn lưu trữ **phải** sử dụng kwarg 
`Hermes_home
` từ 
`initialize()

, không được mã hóa cứng 

~/.Hermes

:

`Python

# CORRECT — profile-scoped
from Hermes_constants import get_Hermes_home
data_dir = get_Hermes_home() / "my-provider"

# WRONG — shared across all profiles
data_dir = Path("~/.Hermes/my-provider").expanduser()

`
``##Thử nghiệm

Xem 
`tests/agent/test_memory_plugin_e2e.py
` để biết mẫu thử nghiệm E2E hoàn chỉnh bằng cách sử dụng nhà cung cấp SQLite thực.

``` python
from agent.memory_manager import MemoryManager`mgr = MemoryManager()
mgr.add_provider(my_provider)
mgr.initialize_all(session_id="test-1", platform="CLI")

# Test tool routing
result = mgr.handle_tool_call("my_tool", \&#123;"action": "add", "content": "test"&#125;)

# Test lifecycle
mgr.sync_all("user msg", "assistant msg")
mgr.on_session_end([])
mgr.shutdown_all()

`

## Thêm lệnh CLI

Các plugin của nhà cung cấp bộ nhớ có thể đăng ký cây lệnh phụ CLI của riêng chúng (ví dụ: 
`Hermes my-provider status

, 
`Hermes my-provider config

). Điều này sử dụng hệ thống khám phá dựa trên quy ước - không cần thay đổi các tệp cốt lõi.

### Cách thức hoạt động
1. Thêm tệp 
`CLI.py
` vào thư mục plugin của bạn

2. Xác định hàm 
`register_CLI(subparser)
` để xây dựng cây argparse
3. Hệ thống plugin bộ nhớ phát hiện ra nó khi khởi động thông qua 
`discover_plugin_CLI_commands()

4. Lệnh của bạn xuất hiện dưới 
`Hermes &lt;provider-name &lt;subcommand
``**Gating nhà cung cấp hoạt động:** Các lệnh CLI của bạn chỉ xuất hiện khi nhà cung cấp của bạn là 
`memory.provider
` đang hoạt động trong config. Nếu người dùng chưa định cấu hình nhà cung cấp của bạn, các lệnh của bạn sẽ không hiển thị trong 
`Hermes --help

.

### Ví dụ

``` python

# plugins/memory/my-provider/CLI.py`def my_command(args):
    """Handler dispatched by argparse."""
    sub = getattr(args, "my_command", None)
    if sub == "status":
        print("Provider is active and connected.")
    elif sub == "config":
        print("Showing config...")
    else:
        print("Usage: Hermes my-provider &lt;status|config")

def register_CLI(subparser) -> None:
    """Build the Hermes my-provider argparse tree.

Called by discover_plugin_CLI_commands() at argparse setup time.
    """
    subs = subparser.add_subparsers(dest="my_command")
    subs.add_parser("status", help="Show provider status")
    subs.add_parser("config", help="Show provider config")
    subparser.set_defaults(func=my_command)

`

### Triển khai tham khảoXem 
`plugins/memory/Honcho/CLI.py
` để biết ví dụ đầy đủ với 13 lệnh phụ, quản lý cấu hình chéo (

--target-profile

) và đọc/ghi cấu hình.

### Cấu trúc thư mục với CLI

`
plugins/memory/my-provider/
├── __init__.py      # MemoryProvider implementation + register()
├── plugin.YAML      # Metadata
├── CLI.py           # register_CLI(subparser) — CLI commands
└── README.md        # Setup instructions

`

## Quy tắc nhà cung cấp duy nhất

Mỗi lần chỉ **một** nhà cung cấp bộ nhớ ngoài có thể hoạt động. Nếu người dùng cố gắng đăng ký một giây, MemoryManager sẽ từ chối nó bằng một cảnh báo. Điều này ngăn ngừa sự phình to của lược đồ công cụ và các chương trình phụ trợ xung đột.

Cấu trúc thư mục​

Nhà cung cấp bộ nhớ ABC​

Cấu trúc thư mục

Nhà cung cấp bộ nhớ ABC