🧠 Zettelkasten Second Memory
An OpenClaw (2026.4/2026.6+) and Hermes Agent plugin that turns AI conversations into a permanent Zettelkasten knowledge base — atomic notes, bi-directional links, knowledge distillation, and intelligent retrieval via MCP tools.
📌 Current Version
Latest Release: v1.0.0-beta.8 — Compatibility adaptation for OpenClaw 2026.6.x and Hermes MCP bridge
✨ Core Features
⚡ Performance Benchmark
Tested on: Node.js v22.22.2, SQLite :memory:
Scale: 1,000 notes creation and search | All tests passed ✅
Current suite: 1,724 unit / integration tests with Vitest
🇨🇳 Looking for Chinese documentation? 点击这里查看简体中文介绍
📐 System Architecture
graph TD
OG[OpenClaw Gateway<br/>MCP Protocol Layer]
HG[Hermes Agent<br/>optional via Streamable HTTP MCP]
subgraph ZK[Zettelkasten Plugin]
MT[MCP Tools]
CLI[CLI Commands]
S[Service Layer]
R[Repository Layer]
ST[Storage Layer]
C[Core Types]
end
DB[(SQLite + Markdown)]
OG --> MT
HG --> MT
MT --> S
CLI --> S
S --> R
R --> ST
ST --> DB
C --> S
C --> R
C --> ST
🇨🇳 Looking for Chinese documentation? 点击这里查看简体中文介绍
🚀 Quick Start
Requirements
- Node.js >= 22.14.0 (requires built-in
node:sqlite) - OpenClaw
2026.4.24/2026.6.x(compatible with >= 2026.4.23) - Hermes Agent
v0.17.0+(optional, for Hermes integration)
Installation
# Clone the repository
git clone https://github.com/cx2002302-lang/zettelkasten-second-memory.git
cd zettelkasten-second-memory
# Install dependencies
npm install
# Run tests
npm test
Use as an OpenClaw Plugin
# 1. Deploy the plugin
bash scripts/deploy.sh
# 2. Configure OpenClaw (edit ~/.openclaw/openclaw.json)
# Ensure plugins.load.paths includes the plugin path
# 3. Restart the Gateway
openclaw gateway restart
# 4. Initialize the database
openclaw zk init
# 5. Health check
openclaw zk doctor
Use with Hermes Agent (Optional)
# 1. Build the MCP bridge
npm run build:bridge
# 2. Start the bridge (adjust DB/notes paths to your OpenClaw setup)
ZETTELKASTEN_DB_PATH=~/.openclaw/zettelkasten/zettelkasten.db \
ZETTELKASTEN_NOTES_DIR=~/.openclaw/zettelkasten/notes \
ZETTELKASTEN_MCP_PORT=9090 \
node dist/mcp/http-bridge.js
# 3. In your Hermes config, add the MCP server:
# mcp_servers:
# zettelkasten:
# type: http
# url: "http://<openclaw-host>:9090/mcp"
# enabled: true
# 4. Verify connectivity
hermes mcp test zettelkasten
See docs/COMPATIBILITY.md for version-specific notes.
🛠️ CLI Commands
🧩 MCP Tools (for AI Agents)
📁 Project Structure
zettelkasten-second-memory/
├── src/ # Plugin source code
│ ├── core/ # Type definitions, constants, utilities
│ ├── storage/ # Database schema, FTS5, template manager
│ ├── repository/ # Data access layer (notes, links, tags, reviews...)
│ ├── service/ # Business logic (CEQRC, distillation, deduplication...)
│ ├── integration/ # OpenClaw integration (agent config, scheduler, hooks)
│ ├── mcp/ # MCP tool definitions and server
│ ├── plugin/ # OpenClaw plugin entry and manifest
│ ├── examples/ # Usage examples
│ └── index.ts # Library entry point
├── skills/brain/ # AI Skill (prompts, rules, workflows)
├── scripts/ # Deployment scripts
├── docs/ # Documentation
├── package.json
├── LICENSE
└── README.md
🧠 Second Memory Skill (AI Integration)
This project includes a Brain Skill that enables AI agents to automatically save conversation knowledge into Zettelkasten:
# Install the Skill
cp -r skills/brain ~/.openclaw/skills/zettelkasten-brain
# Activate the Skill
openclaw config set agents.defaults.skills '["zettelkasten-brain"]'
# Restart the Gateway
openclaw gateway restart
Once activated, the AI will automatically:
- 🔍 Search the knowledge base before answering
- 📝 Recognize and save important information
- 🔗 Intelligently establish note associations
- 📦 Archive discussions when sessions end
📊 Database Schema
The system uses SQLite. Core tables include:
FTS5 virtual tables provide full-text search capabilities.
🧪 Testing
# Run all tests
npm test
Current test coverage:
- Repository layer (CRUD, search, links, tags)
- Service layer (CEQRC, distillation, deduplication, parsing)
- Integration layer (configuration, scheduling)
- MCP Server (tool registration and invocation)
📜 License
MIT © Zettelkasten Contributors
🙏 Acknowledgements
- Inspired by Niklas Luhmann's Zettelkasten method
- Built on the OpenClaw plugin architecture
- Uses SQLite FTS5 for full-text search