kimi-code-memory-mcp-server 0.1.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,144 @@
+# Architecture
+
+This document explains how Kimi Code Memory MCP Server is structured, how data flows, and why we made the key design choices.
+
+## Design Principles
+
+1. **Markdown is the source of truth**
+   - Every memory is a `.md` file with YAML frontmatter.
+   - `index.json` is a rebuildable cache, not the database.
+   - Users can edit files directly; running `sync_workspace_index` repairs the cache.
+
+2. **Local-first, offline, zero external dependencies**
+   - No vector database, no graph database, no cloud API.
+   - Works entirely on the local filesystem.
+
+3. **Structured before fuzzy**
+   - Memories are written into typed folders (`decisions/`, `knowledge/`, `rules/`, `reference/`).
+   - Keyword search + tags + theme tracing are the default retrieval model.
+   - Optional embedding/LLM layers can be added later as plugins.
+
+4. **Cross-session context recovery**
+   - The server reads Kimi Code CLI's `wire.jsonl` to rebuild recent conversation context.
+   - This is intentionally Kimi-specific; other CLI adapters can be added later.
+
+## Data Flow
+
+```text
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│  Kimi Code CLI  │────▶│  wire.jsonl      │────▶│ wire-context.ts │
+│  (conversation) │     │  (event stream)  │     │ (parser)        │
+└─────────────────┘     └──────────────────┘     └────────┬────────┘
+                                                          │
+                                                          ▼
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│  Agent tools    │◀────│  MCP server      │◀────│  context-tools  │
+│  remember/      │     │  src/server.ts   │     │                 │
+│  search/        │     │                  │     │                 │
+│  trace_theme/   │     │                  │     │                 │
+└─────────────────┘     └────────┬─────────┘     └─────────────────┘
+                                 │
+           ┌─────────────────────┼─────────────────────┐
+           │                     │                     │
+           ▼                     ▼                     ▼
+   ┌───────────────┐    ┌───────────────┐    ┌───────────────┐
+   │ memory-tools  │    │ theme-tools   │    │ system-tools  │
+   │ CRUD memory   │    │ tag/trace/    │    │ organize/     │
+   │ files         │    │ refine        │    │ sync/bootstrap│
+   └───────┬───────┘    └───────┬───────┘    └───────┬───────┘
+           │                    │                    │
+           ▼                    ▼                    ▼
+   ┌───────────────┐    ┌───────────────┐    ┌───────────────┐
+   │ memory-store  │    │ theme-manager │    │ refined-      │
+   │ (.md I/O)     │    │ (themes/*.json)│   │ manager       │
+   └───────┬───────┘    └───────────────┘    │ (refined/     │
+           │                                  │  refined.sqlite)│
+           ▼                                  └───────────────┘
+   ┌───────────────┐
+   │ IndexDao      │
+   │ (index.json)  │
+   └───────────────┘
+```
+
+## Module Responsibilities
+
+| File | Responsibility |
+|------|----------------|
+| `src/server.ts` | MCP server entry, registers tools, starts stdio transport. |
+| `src/config.ts` | Default paths, environment variable handling (`MEMORY_STORE_ROOT`, `MEMORY_SESSIONS_ROOT`, `KIMI_CODE_HOME`). |
+| `src/tools/index.ts` | Tool schemas, validation, and dispatch. |
+| `src/tools/memory-tools.ts` | `remember`, `recall`, `recall_recent`, `search`, `list`, `list_tags`, `delete`, `move`. |
+| `src/tools/context-tools.ts` | `load_workspace_context`, `load_more_context`, `search_context`, `load_turn_context`. |
+| `src/tools/theme-tools.ts` | `tag_theme`, `trace_theme`, `list_themes`, `refine_session_turns`. |
+| `src/tools/system-tools.ts` | `organize_memories`, `sync_workspace_index`, `bootstrap_workspace`, `get_current_workspace`. |
+| `src/dao/index.ts` | `index.json` v3-kv DAO with structure-hash consistency check. |
+| `src/dao/memory-store.ts` | Markdown file read/write and frontmatter handling. |
+| `src/context/wire-context.ts` | Parses Kimi Code CLI `wire.jsonl` into conversation rounds. |
+| `src/theme-manager.ts` | Reads/writes `themes/<theme>.json`. |
+| `src/refined-manager.ts` | Stores refined turn summaries in `refined/refined.sqlite`. |
+| `src/utils/frontmatter.ts` | YAML frontmatter parser and serializer. |
+| `src/utils/paths.ts` | Path helpers and storage root resolution. |
+| `src/utils/validation.ts` | Input sanitization (`sanitizeKey`, `sanitizeFolder`). |
+
+## `index.json` v3-kv
+
+`index.json` is a fast cache over the Markdown files on disk.
+
+```json
+{
+  "version": "v3-kv",
+  "meta": {
+    "structureHash": "sha256-of-directory-tree",
+    "updatedAt": "2026-06-24T12:00:00.000Z"
+  },
+  "index": {
+    "memory/decisions/choose-sqlite.md": {
+      "key": "choose-sqlite",
+      "folder": "memory/decisions",
+      "title": "Choose Sqlite",
+      "tags": ["decision", "database"],
+      "createdAt": "...",
+      "updatedAt": "..."
+    }
+  },
+  "folderComments": {
+    "memory/decisions": "Architecture and product decisions"
+  }
+}
+```
+
+- `structureHash` is computed from the file tree.
+- If the hash changes (e.g., external edit), the index is rebuilt on next access.
+- The DAO also supports migration from older index formats.
+
+## Memory Lifecycle
+
+1. **Capture** — Agent writes a memory via `remember`.
+2. **Index** — `IndexDao` updates `index.json` and writes the `.md` file.
+3. **Recall** — Agent uses `search`, `recall`, or `recall_recent` to retrieve memories.
+4. **Distill** — `organize_memories` condenses `memory/` into `essence/essence.md` (≤15 KB).
+5. **Trace** — `tag_theme` and `trace_theme` connect memories and conversation turns into evolving themes.
+6. **Archive/Move** — `move` renames or relocates a memory; `delete` removes it.
+
+## Why No Vector Database by Default?
+
+Vector search is excellent for:
+- Fuzzy "something like this" queries
+- Synonym matching
+- Large corpora where keyword recall is insufficient
+
+For a coding assistant, however, the most valuable memories are usually:
+- Exact decisions (`decisions/`)
+- Explicit conventions (`rules/`)
+- Known project facts (`knowledge/`)
+
+These are best retrieved by **path + tags + keywords + theme links**, which is fast, deterministic, and fully explainable.
+
+We keep the door open for optional embedding plugins, but the default path is intentionally lightweight.
+
+## Security Notes
+
+- `sanitizeKey` and `sanitizeFolder` reject path traversal attempts.
+- `move` refuses to overwrite an existing target.
+- Writes use temp-file + rename for atomicity.
+- Sensitive files (`.env`, SSH keys, etc.) are never read by the server.

package/docs/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing
+
+Thank you for your interest in improving Kimi Code Memory MCP Server!
+
+## Development Setup
+
+```bash
+git clone https://github.com/Zehee/kimi-code-memory-mcp-server.git
+cd kimi-code-memory-mcp-server
+npm install
+```
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `npm test` | Run integration tests |
+| `npm run lint` | Run ESLint |
+| `npm run lint:fix` | Run ESLint with auto-fix |
+| `npm run format` | Format code with Prettier |
+| `npm start` | Start the MCP server |
+
+## Before Submitting a Pull Request
+
+1. **Run tests**
+   ```bash
+   npm test
+   ```
+
+2. **Run linting**
+   ```bash
+   npm run lint
+   ```
+
+3. **Format code**
+   ```bash
+   npm run format
+   ```
+
+4. **Update documentation** if your change affects user-facing behavior.
+
+5. **Update `CHANGELOG.md`** under the `Unreleased` section.
+
+## Code Style
+
+- We use ESLint and Prettier. Run `npm run format` before committing.
+- Use JSDoc comments for public functions.
+- Keep functions small and focused.
+- Prefer explicit error messages over silent failures.
+
+## Commit Messages
+
+Use clear, descriptive commit messages in English or Chinese. For example:
+
+```text
+feat: add search_context tool test
+docs: update README quick start example
+fix: handle missing frontmatter in recall
+```
+
+## Reporting Bugs
+
+Use the [bug report issue template](../.github/ISSUE_TEMPLATE/bug_report.md).
+
+Include:
+- Node.js version
+- Operating system
+- Steps to reproduce
+- Expected vs actual behavior
+- Relevant logs or error messages
+
+## Proposing Features
+
+Use the [feature request issue template](../.github/ISSUE_TEMPLATE/feature_request.md).
+
+Explain:
+- The problem you want to solve
+- Your proposed solution
+- Why it fits the project's design principles
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/docs/CONTRIBUTING.zh-CN.md

@@ -0,0 +1,83 @@
+# 贡献指南
+
+感谢你对 Kimi Code Memory MCP Server 的兴趣！
+
+## 开发环境
+
+```bash
+git clone https://github.com/Zehee/kimi-code-memory-mcp-server.git
+cd kimi-code-memory-mcp-server
+npm install
+```
+
+## 脚本
+
+| 脚本 | 用途 |
+|------|------|
+| `npm test` | 运行集成测试 |
+| `npm run lint` | 运行 ESLint |
+| `npm run lint:fix` | 自动修复 ESLint 问题 |
+| `npm run format` | 用 Prettier 格式化代码 |
+| `npm start` | 启动 MCP 服务器 |
+
+## 提交 Pull Request 前
+
+1. **运行测试**
+   ```bash
+   npm test
+   ```
+
+2. **运行 lint**
+   ```bash
+   npm run lint
+   ```
+
+3. **格式化代码**
+   ```bash
+   npm run format
+   ```
+
+4. **更新文档**（如果你的改动影响用户可见行为）
+
+5. **更新 `CHANGELOG.md`**（在 `Unreleased` 区域添加条目）
+
+## 代码风格
+
+- 使用 ESLint 和 Prettier。提交前运行 `npm run format`。
+- 公共函数使用 JSDoc 注释。
+- 保持函数小而聚焦。
+- 优先给出明确的错误信息，而不是静默失败。
+
+## 提交信息
+
+使用清晰、描述性的提交信息，英文或中文均可。例如：
+
+```text
+feat: add search_context tool test
+docs: update README quick start example
+fix: handle missing frontmatter in recall
+```
+
+## 报告 Bug
+
+使用 [Bug 报告 issue 模板](../.github/ISSUE_TEMPLATE/bug_report.md)。
+
+请包含：
+- Node.js 版本
+- 操作系统
+- 复现步骤
+- 预期行为 vs 实际行为
+- 相关日志或错误信息
+
+## 提议新功能
+
+使用 [功能请求 issue 模板](../.github/ISSUE_TEMPLATE/feature_request.md)。
+
+请说明：
+- 想解决什么问题
+- 你的方案
+- 为什么它符合项目的设计原则
+
+## 许可证
+
+通过贡献代码，你同意你的贡献采用 MIT 许可证。

package/docs/search-logic.md

@@ -0,0 +1,157 @@
+# Search Logic
+
+The project provides two search tools with different scopes and implementations:
+
+- `search` — searches across persisted Markdown memories.
+- `search_context` — searches across Kimi Code CLI session wires (`wire.jsonl`).
+
+---
+
+## 1. `search` — Memory Search
+
+Source: `src/tools/memory-tools.ts` (`handleSearch`)
+
+### Flow
+
+```mermaid
+flowchart TD
+    A[Receive query + optional folder] --> B[Load index.json via IndexDao]
+    B --> C[Iterate over .md entries]
+    C --> D{Folder filter?}
+    D -->|Yes| E[Skip entries outside folder]
+    D -->|No| F[Build haystack: title + key]
+    E --> F
+    F --> G{Haystack contains needle?}
+    G -->|Yes| H[Return title match]
+    G -->|No| I[Open .md file and search body]
+    I --> J{Body contains needle?}
+    J -->|Yes| K[Collect up to 3 matching lines]
+    J -->|No| L[Skip entry]
+    H --> M[Return items]
+    K --> M
+```
+
+### Key behavior
+
+- The query is converted to lowercase and matched against a lowercased haystack.
+- Matching is **title/key first, body fallback**.
+- When the body matches, up to 3 matching lines are returned as snippets.
+- Results are not ranked by score; they appear in `index.json` iteration order.
+
+### Example result
+
+```json
+{
+  "items": [
+    {
+      "key": "use-sqlite-cache",
+      "folder": "memory/decisions",
+      "title": "Use SQLite for Cache",
+      "matches": ["We chose SQLite over Redis because..."]
+    }
+  ]
+}
+```
+
+---
+
+## 2. `search_context` — Cross-Session Wire Search
+
+Sources:
+
+- Entry point: `src/tools/context-tools.ts` (`handleSearchContext`)
+- Core search: `src/context/wire-context.ts` (`searchWireContext`)
+- Refined storage: `src/refined-manager.ts` (`searchRefinedTurns`)
+
+### Flow
+
+```mermaid
+flowchart TD
+    A[Receive query + options] --> B{Refined SQLite
+    has matches?}
+    B -->|Yes| C[Load original turns from wire.jsonl]
+    B -->|No| D[Full scan all workspace sessions]
+    C --> E{Wire file exists?}
+    E -->|Yes| F[Build matches & hits]
+    E -->|No| G[Build match from refined summary]
+    D --> F
+    F --> H[Group hits by session]
+    G --> M[Return refined-only matches]
+    H --> I[Expand clusters around hits]
+    I --> J[Refine unrefined turns in clusters]
+    J --> K[Save refined turns to SQLite]
+    K --> L[Return matches, clusters, skippedSessions]
+    M --> L
+```
+
+### Two-phase search
+
+#### Phase 1 — Refined SQLite index
+
+`searchWireContext` first queries `refined/refined.sqlite` through `RefinedManager.searchRefinedTurns`:
+
+- Splits the query into lowercase terms.
+- Uses SQL `LIKE` to match all terms against `summary`, `facts`, and `notes` columns.
+- Returns matches sorted by keyword frequency score.
+- For each refined match, it tries to load the original turn from the session's `wire.jsonl`.
+  - If the wire still exists, the full turn content is used for the match and the turn becomes a hit for clustering.
+  - If the wire is missing, the refined record itself is returned as a match. Its `summary` becomes the `agent` text and `snippet`, so the key information is preserved even without the original wire.
+  - If matches are found, it returns early.
+
+#### Phase 2 — Full wire scan fallback
+
+If refined search returns nothing, `searchWireContext` falls back to scanning every workspace session:
+
+- `findAllWorkspaceSessions()` discovers all `wire.jsonl` files for the current workspace.
+- Each wire is parsed into turns.
+- Each turn is scored by keyword presence in `user` + `agentText`.
+- Matching turns become hits.
+
+### Clustering & refinement
+
+Back in `handleSearchContext`:
+
+1. **Group hits by session**. Only hits backed by an existing wire participate in clustering; refined-only matches are returned as standalone results.
+2. **Expand clusters**: for each hit, absorb nearby turns within `cluster_gap_seconds` (default 90s), up to `max_cluster_size`.
+3. **Refine missing turns**: turns inside clusters that are not yet in SQLite are passed to `refinedManager.refineTurn()` and saved in batch.
+4. **Return** `matches`, `clusters`, `skippedSessions`, and `refinedCount`.
+
+### Example result
+
+```json
+{
+  "query": "SQLite cache",
+  "totalMatches": 2,
+  "matches": [
+    { "sessionId": "session_xxx", "turnId": 5, "score": 3, "user": "...", "agent": "..." }
+  ],
+  "clusters": [
+    { "sessionId": "session_xxx", "hitTurnId": 5, "memberCount": 3, "members": [...] }
+  ],
+  "skippedSessions": [],
+  "refinedCount": 1
+}
+```
+
+---
+
+## Comparison
+
+| Dimension | `search` | `search_context` |
+|-----------|----------|------------------|
+| Target | Markdown memory files | Kimi Code CLI `wire.jsonl` sessions |
+| Index | `index.json` v3-kv | `refined/refined.sqlite` + full scan fallback |
+| Matching | Substring in title/key/body | Substring in refined summary/facts/notes, or turn text |
+| Ranking | None | Score by keyword frequency |
+| Clustering | No | Yes, around hits |
+| Side effect | None | Writes refined turns to SQLite |
+
+---
+
+## Environment variables that affect search
+
+| Variable | Impact |
+|----------|--------|
+| `MEMORY_STORE_ROOT` | Changes where `index.json` and `refined/refined.sqlite` are located. |
+| `MEMORY_SESSIONS_ROOT` | Changes where `search_context` looks for `wire.jsonl` files. |
+| `KIMI_CODE_HOME` | Alternative to `MEMORY_SESSIONS_ROOT`; sessions are read from `<KIMI_CODE_HOME>/sessions`. |

package/docs/search-logic.zh-CN.md

@@ -0,0 +1,157 @@
+# 搜索逻辑
+
+本项目提供两个搜索工具，作用域和实现各不相同：
+
+- `search` —— 在持久化的 Markdown 记忆文件中搜索。
+- `search_context` —— 在 Kimi Code CLI 的会话 wire（`wire.jsonl`）中搜索。
+
+---
+
+## 1. `search` —— 记忆搜索
+
+源码：`src/tools/memory-tools.ts`（`handleSearch`）
+
+### 流程
+
+```mermaid
+flowchart TD
+    A[接收 query + 可选 folder] --> B[通过 IndexDao 加载 index.json]
+    B --> C[遍历所有 .md 条目]
+    C --> D{是否指定 folder?}
+    D -->|是| E[跳过不在该 folder 的条目]
+    D -->|否| F[构造 haystack: title + key]
+    E --> F
+    F --> G{haystack 包含 needle?}
+    G -->|是| H[返回 title 匹配]
+    G -->|否| I[打开 .md 文件搜索正文]
+    I --> J{正文包含 needle?}
+    J -->|是| K[收集最多 3 行匹配片段]
+    J -->|否| L[跳过该条目]
+    H --> M[返回 items]
+    K --> M
+```
+
+### 关键行为
+
+- query 被转小写，与同样小写化的 haystack 做子串匹配。
+- 匹配策略是**标题/key 优先，正文兜底**。
+- 正文命中时，返回最多 3 行包含关键词的片段。
+- 结果没有打分排序，按 `index.json` 的遍历顺序返回。
+
+### 返回示例
+
+```json
+{
+  "items": [
+    {
+      "key": "use-sqlite-cache",
+      "folder": "memory/decisions",
+      "title": "Use SQLite for Cache",
+      "matches": ["We chose SQLite over Redis because..."]
+    }
+  ]
+}
+```
+
+---
+
+## 2. `search_context` —— 跨会话历史搜索
+
+源码：
+
+- 入口：`src/tools/context-tools.ts`（`handleSearchContext`）
+- 核心搜索：`src/context/wire-context.ts`（`searchWireContext`）
+- 精炼存储：`src/refined-manager.ts`（`searchRefinedTurns`）
+
+### 流程
+
+```mermaid
+flowchart TD
+    A[接收 query + options] --> B{Refined SQLite
+    有命中?}
+    B -->|是| C[从 wire.jsonl 加载原始 turn]
+    B -->|否| D[全量扫描当前工作区所有 session]
+    C --> E{wire 文件存在?}
+    E -->|是| F[构建 matches & hits]
+    E -->|否| G[从 refined summary 构建 match]
+    D --> F
+    F --> H[按 session 分组 hits]
+    G --> M[返回 refined-only matches]
+    H --> I[围绕命中点扩展 cluster]
+    I --> J[精炼 cluster 中未精炼的 turn]
+    J --> K[将精炼结果写入 SQLite]
+    K --> L[返回 matches, clusters, skippedSessions]
+    M --> L
+```
+
+### 两阶段搜索
+
+#### 第一阶段 —— Refined SQLite 索引
+
+`searchWireContext` 首先通过 `RefinedManager.searchRefinedTurns` 查询 `refined/refined.sqlite`：
+
+- 把 query 拆成小写关键词。
+- 用 SQL `LIKE` 要求所有关键词都匹配 `summary`、`facts`、`notes` 列。
+- 按关键词出现频次打分并排序返回。
+- 对每个 refined 命中，尝试从对应 session 的 `wire.jsonl` 加载原始 turn。
+  - 如果 wire 仍存在，使用完整 turn 内容构建 match，并作为 hit 参与 cluster 扩展。
+  - 如果 wire 已不存在，直接用 refined 记录本身作为 match 返回。其 `summary` 会作为 `agent` 文本和 `snippet`，即使没有原始 wire，关键信息也不会丢失。
+  - 如果有命中，直接返回，不再走全量扫描。
+
+#### 第二阶段 —— 全量 wire 扫描兜底
+
+如果 refined 搜索没有结果，`searchWireContext` 会回退到扫描当前工作区的所有 session：
+
+- `findAllWorkspaceSessions()` 发现当前工作区的所有 `wire.jsonl`。
+- 逐个解析为 turns。
+- 对每个 turn 的 `user` + `agentText` 做关键词打分。
+- 命中的 turns 成为 hits。
+
+### 聚类与精炼
+
+回到 `handleSearchContext`：
+
+1. **按 session 分组 hits**。只有存在 wire 的 hit 才会参与 cluster；纯 refined 命中作为独立结果返回。
+2. **扩展 cluster**：对每个命中点，吸收 `cluster_gap_seconds`（默认 90 秒）内的相邻 turn，最多 `max_cluster_size` 个。
+3. **精炼缺失 turn**：cluster 中尚未写入 SQLite 的 turn 会批量传给 `refinedManager.refineTurn()` 并保存。
+4. **返回** `matches`、`clusters`、`skippedSessions`、`refinedCount`。
+
+### 返回示例
+
+```json
+{
+  "query": "SQLite cache",
+  "totalMatches": 2,
+  "matches": [
+    { "sessionId": "session_xxx", "turnId": 5, "score": 3, "user": "...", "agent": "..." }
+  ],
+  "clusters": [
+    { "sessionId": "session_xxx", "hitTurnId": 5, "memberCount": 3, "members": [...] }
+  ],
+  "skippedSessions": [],
+  "refinedCount": 1
+}
+```
+
+---
+
+## 对比
+
+| 维度 | `search` | `search_context` |
+|------|----------|------------------|
+| 搜索对象 | Markdown 记忆文件 | Kimi Code CLI `wire.jsonl` 会话 |
+| 索引 | `index.json` v3-kv | `refined/refined.sqlite` + 全量扫描兜底 |
+| 匹配方式 | title/key/正文子串匹配 | refined summary/facts/notes 或 turn 文本子串匹配 |
+| 排序 | 无 | 按关键词频次打分排序 |
+| 聚类 | 无 | 围绕命中点扩展 cluster |
+| 副作用 | 无 | 将精炼 turn 写入 SQLite |
+
+---
+
+## 影响搜索的环境变量
+
+| 变量 | 影响 |
+|------|------|
+| `MEMORY_STORE_ROOT` | 改变 `index.json` 和 `refined/refined.sqlite` 的位置。 |
+| `MEMORY_SESSIONS_ROOT` | 改变 `search_context` 查找 `wire.jsonl` 的位置。 |
+| `KIMI_CODE_HOME` | `MEMORY_SESSIONS_ROOT` 的替代方案；会话从 `<KIMI_CODE_HOME>/sessions` 读取。 |

package/examples/README.md

@@ -0,0 +1,34 @@
+# Examples
+
+This directory contains a sample workspace that demonstrates the storage layout and content conventions used by Kimi Code Memory MCP Server.
+
+## sample-workspace/
+
+```text
+sample-workspace/
+├── index.json              # v3-kv index cache
+├── essence/
+│   └── essence.md          # workspace digest
+├── memory/
+│   ├── decisions/          # architecture and product decisions
+│   ├── knowledge/          # project-specific knowledge
+│   ├── rules/              # conventions and guardrails
+│   └── reference/          # external references
+├── notes/                  # scratch notes
+└── themes/                 # theme associations
+```
+
+## How to Use
+
+1. Copy `sample-workspace/` to your own location.
+2. Set `MEMORY_STORE_ROOT` to the parent directory of `sample-workspace/`.
+3. Or rename `sample-workspace/` to match your workspace ID and place it under `~/.kimi-code-memory/`.
+
+## Files
+
+- `memory/decisions/choose-sqlite-cache.md` — example decision record
+- `memory/knowledge/project-tech-stack.md` — example knowledge record
+- `memory/rules/no-plaintext-secrets.md` — example rule
+- `memory/reference/mcp-spec.md` — example external reference
+- `essence/essence.md` — example workspace digest
+- `themes/cache-design.json` — example theme association

package/examples/sample-workspace/essence/essence.md

@@ -0,0 +1,26 @@
+---
+key: 'essence'
+title: 'Workspace Essence'
+tags:
+  - essence
+  - workspace-memory
+updatedAt: '2026-06-20T10:20:00.000Z'
+---
+
+# Workspace Essence: Sample Project
+
+## Decisions
+
+- Use SQLite for the cache layer to keep deployment simple.
+
+## Knowledge
+
+- Runtime: Node.js >= 18, MCP over stdio, Markdown + JSON index storage.
+
+## Rules
+
+- No plaintext secrets in memory.
+
+## References
+
+- MCP specification at https://modelcontextprotocol.io/.