AgentSoul

Give OpenCode a soul — personality injection and long-term memory for your AI agent.

Installation

npm install -g @neomei/agentsoul

如果安装后提示 command not found: agentsoul，说明 npm 全局 bin 目录不在 PATH 中。请配置 npm 全局路径：

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

或使用 npx 直接运行（无需全局安装）：

npx @neomei/agentsoul setup
npx @neomei/agentsoul chat

Quick Start

# 1. Configure your agent's personality (auto-registers plugin)
agentsoul setup

# 2. Launch OpenCode with soul injection
agentsoul chat

Commands

Command	Description
agentsoul setup	Interactive configuration wizard (auto-registers plugin)
agentsoul uninstall	Remove plugin from opencode config
agentsoul chat	Launch OpenCode TUI with soul injection
agentsoul run <message>	Single-shot with soul injection
agentsoul serve [port]	Headless server with soul injection
agentsoul memory list	Show recent conversations
agentsoul memory search <query>	Search conversation history
agentsoul memory clear	Clear all memories

How It Works

AgentSoul injects personality files into every OpenCode session:

1. Soul Files (~/.agentsoul/soul/)

   • IDENTITY.md — Who your agent is
   • SOUL.md — Core principles and speaking style
   • USER.md — Who you are and your relationship

2. Memory (~/.agentsoul/memory.db)

   • SQLite storage for conversation history
   • Recent memories are automatically injected into new sessions

3. OpenCode Plugin — Registered in ~/.config/opencode/opencode.json

   • Hooks into experimental.chat.system.transform to inject soul before every LLM call
   • Hooks into chat.message to persist user messages
   • Survives context compaction automatically

Configuration

After agentsoul setup, edit the files directly:

~/.agentsoul/soul/IDENTITY.md   # Name, age, personality
~/.agentsoul/soul/SOUL.md       # Core principles, speaking style
~/.agentsoul/soul/USER.md       # User relationship

Integration with OpenCode Feishu

AgentSoul works with @neomei/opencode-feishu to give your Feishu bot a soul.

Prerequisite: Both plugins must be registered in ~/.config/opencode/opencode.json:

{
  "plugin": [
    "@neomei/agentsoul",
    "@neomei/opencode-feishu"
  ]
}

Setup:

# 1. Configure AgentSoul personality
agentsoul setup

# 2. Configure Feishu connection
npx @neomei/opencode-feishu setup

# 3. Start OpenCode serve with both plugins loaded
opencode serve --port 19876

When a Feishu user sends a message, OpenCode processes it through both plugins:

• AgentSoul injects personality into the system prompt
• opencode-feishu handles the Feishu WebSocket and message formatting

Memory (conversation history) is persisted automatically.

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   agentsoul     │────▶│   soul/*.md     │────▶│  stdin inject   │
│   CLI / Plugin  │     │  (personality)  │     │  (opencode run) │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                                               │
         ▼                                               ▼
┌─────────────────┐                            ┌─────────────────┐
│  memory.db      │◀───────────────────────────│  opencode TUI   │
│  (SQLite)       │      save conversations    │  / serve        │
└─────────────────┘                            └─────────────────┘

License

MIT