Zettelkasten Second Memory

🧠 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.

English · 简体中文

📌 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