🧠 Zettelkasten Second Memory

An OpenClaw plugin that turns AI conversations into a permanent Zettelkasten knowledge base — atomic notes, bi-directional links, knowledge distillation, and intelligent retrieval.

English · 简体中文

📌 Current Version

Latest Release: v1.0.0-beta.4 — Test Suite + Input Validation + Performance Benchmark

✨ Core Features

⚡ Performance Benchmark

Tested on: Node.js v22.22.2, SQLite :memory:, 2026-05-12
Scale: 10,000 notes, 30,000 links | All 7 thresholds passed ✅
Full report: plans/PERFORMANCE-BENCHMARK.md

🇨🇳 Looking for Chinese documentation? 点击这里查看简体中文介绍

📐 System Architecture

┌─────────────────────────────────────────────────────────┐
│                    OpenClaw Gateway                      │
│                  (MCP Protocol Layer)                    │
└──────────────────────┬──────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────────────┐
│              Zettelkasten Plugin                         │
│  ┌─────────┐  ┌──────────┐  ┌─────────────┐            │
│  │  MCP    │  │   CLI    │  │  Session    │            │
│  │ Tools   │  │ Commands │  │   Hook      │            │
│  └────┬────┘  └────┬─────┘  └──────┬──────┘            │
│       └─────────────┴───────────────┘                   │
│                         │                                │
│  ┌──────────┬───────────┼───────────┬──────────┐        │
│  │ Service  │ Repository│  Storage  │  Core    │        │
│  │ Layer    │  Layer    │  Layer    │  Types   │        │
│  │          │           │           │          │        │
│  │• Note    │• NoteRepo │• DB Schema│• Types   │        │
│  │• Link    │• LinkRepo │• FTS5     │• Constants│       │
│  │• CEQRC   │• TagRepo  │• Templates│• Utils   │        │
│  │• Distill │• ReviewRepo│          │          │        │
│  └──────────┴───────────┴───────────┴──────────┘        │
│                         │                                │
│                    SQLite + Markdown                     │
└─────────────────────────────────────────────────────────┘

🇨🇳 Chinese users: 点击这里查看中文介绍

🚀 Quick Start

Requirements

• Node.js >= 22.14.0 (requires built-in node:sqlite)
• OpenClaw 2026.4.24 (developed & tested on this version; compatible with >= 2026.4.23)

Installation

# Clone the repository
git clone https://github.com/YOUR_USERNAME/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 as a Standalone Library

import { createZettelkasten } from "zettelkasten-second-memory";

// Create a client
const zk = await createZettelkasten("./data/zettelkasten.db", "./data");

// Create a note
const note = await zk.createNote({
  title: "Hello Zettelkasten",
  content: "This is my first atomic note.",
  tags: ["intro", "demo"],
  type: "atomic",
});

// Search
const results = zk.searchNotes("atomic note", 10);
console.log(results);

🛠️ CLI Commands

🧩 MCP Tools (for AI Agents)

📁 Project Structure

zettelkasten-second-memory/
├── src/
│   ├── 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
│   ├── skills/brain/       # AI Skill (prompts, rules, evolution scripts)
│   ├── examples/           # Usage examples
│   └── index.ts            # Library entry point
├── scripts/                # Deployment scripts
├── plans/                  # Design documents and architecture diagrams
├── 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 src/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

# Watch mode
npm run test:watch

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