@suwujs/codex-vault 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fayon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# Codex-Vault
+
+[English](README.md) | [中文](README.zh-CN.md)
+
+> A knowledge vault that works with any LLM agent.
+> Your notes, your git, your data.
+
+## The Problem
+
+LLM agents forget everything between sessions. You re-explain the same context, lose decisions made three conversations ago, and the knowledge never compounds.
+
+## The Solution
+
+A structured vault + 3 hooks that give your agent persistent memory. Works with **Claude Code** and **Codex CLI**. Just markdown and git.
+
+```
+You: "start session"
+Agent: *reads North Star, checks active projects, scans recent changes*
+Agent: "You're working on the API redesign. Last session you decided
+        to split the coordinator pattern. There's an open question
+        about error handling."
+```
+
+## 30-Second Start
+
+```bash
+# From your project directory:
+git clone https://github.com/sukbearai/codex-vault.git /tmp/codex-vault
+bash /tmp/codex-vault/plugin/install.sh   # integrated mode — installs vault + hooks into your project
+claude                                  # or: codex
+```
+
+Fill in `vault/brain/North Star.md` with your goals, then start talking.
+
+> **Standalone mode**: run `install.sh` from inside the codex-vault repo itself to use `vault/` as the working directory.
+
+## How It Works
+
+```
+You speak
+    |
+    v
+classify hook (categorizes: decision? win? project update?)
+    |
+    v
+Agent writes notes (guided by instructions.md)
+    |
+    v
+validate hook (checks: frontmatter? wikilinks? correct folder?)
+    |
+    v
+git commit (persistent)
+    |
+    v
+Next session → session-start hook injects context back
+```
+
+Three hooks power the loop:
+
+| Hook | When | What |
+|------|------|------|
+| **session-start** | Agent starts | Injects North Star goals, recent git changes, active work, vault file listing |
+| **classify-message** | Every message | Detects decisions, wins, project updates — hints the agent where to file them |
+| **validate-write** | After writing `.md` | Checks frontmatter and wikilinks — catches mistakes before they stick |
+
+## Supported Agents
+
+| Agent | Hooks | Skills | Status |
+|-------|-------|--------|--------|
+| Claude Code | 3 hooks via `.claude/settings.json` | `/dump` `/recall` `/ingest` `/wrap-up` | Full support |
+| Codex CLI | 3 hooks via `.codex/hooks.json` | `$dump` `$recall` `$ingest` `$wrap-up` | Full support |
+| Other | Write an adapter ([docs/adding-an-agent.md](docs/adding-an-agent.md)) | Depends on agent | Community |
+
+## Vault Structure
+
+```
+vault/
+  Home.md                 Entry point — current focus, quick links
+  log.md                  Append-only operation log — grep-parseable
+  brain/
+    North Star.md         Goals and focus — read every session
+    Memories.md           Memory index
+    Key Decisions.md      Decisions worth recalling
+    Patterns.md           Recurring patterns
+  work/
+    Index.md              Map of all work notes
+    active/               Current projects
+    archive/              Completed work
+  templates/              Note templates (Work Note, Decision Record, Thinking Note)
+  thinking/               Scratchpad — promote findings, then delete
+  sources/                Raw source documents — immutable, LLM reads only
+  reference/              Saved answers and analyses from query writeback
+```
+
+Eight folders. Five note types. That's it.
+
+## Skills
+
+User-invoked skills — the agent suggests them, but only executes when you explicitly run one:
+
+| Skill | What It Does |
+|-------|-------------|
+| `/dump` | Freeform capture — say anything, agent classifies and routes to the right notes |
+| `/wrap-up` | End-of-session review — verify notes, update indexes, check links |
+| `/ingest` | Process a source document into wiki pages with cross-links |
+| `/recall` | On-demand memory retrieval — search the vault for a topic and synthesize |
+
+The classify hook detects intent (decision, win, project update, query, ingest) and suggests the right skill. You decide whether to run it — the agent never auto-writes vault notes.
+
+Claude Code uses `/skill-name`, Codex CLI uses `$skill-name`. Both read from their respective `.claude/skills/` and `.codex/skills/` directories.
+
+### Prompt Templates
+
+Copy-paste ready — replace `<>` with your content:
+
+**`/dump`**
+```
+/dump We decided to use <option A> over <option B> because <reason>
+/dump <project> is done. Key outcome: <what was achieved>
+/dump Pattern noticed: <description>
+/dump Remember: <anything you want the agent to recall next session>
+```
+
+**`/recall`**
+```
+/recall <keyword>
+/recall how did we decide on <topic>
+/recall <project> progress
+```
+
+**`/ingest`**
+```
+/ingest <URL>
+/ingest sources/<filename>.md
+```
+
+**`/wrap-up`** — no arguments needed, the agent scans the session automatically.
+
+## Usage Scenarios
+
+See [docs/usage.md](docs/usage.md) — 7 real scenarios from first session to project completion, with exact commands and expected output.
+
+## Design Principles
+
+1. **Data sovereignty** — your markdown, your git, your machine. No cloud lock-in.
+2. **Agent-agnostic** — hooks are the universal interface. One vault, multiple agents.
+3. **Minimal by default** — 3 hooks, ~100 lines of instructions. Add complexity only when needed.
+4. **Graph-first** — folders group by purpose, [[wikilinks]] group by meaning. Links are the primary organization tool.
+5. **Future-proof** — if models get built-in memory, the vault still has value as auditable, portable, git-tracked local storage.
+
+## Customization
+
+| What | How |
+|------|-----|
+| Your goals | Edit `brain/North Star.md` |
+| New note types | Add templates to `templates/`, update `plugin/instructions.md` |
+| More signals | Add patterns to `plugin/hooks/classify-message.py` |
+| New agent | Add hooks and skills in `plugin/` ([guide](docs/adding-an-agent.md)) |
+
+## Requirements
+
+- Git
+- Python 3
+- One of: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex CLI](https://github.com/openai/codex)
+- Optional: [Obsidian](https://obsidian.md) (for graph view, backlinks, visual browsing)
+
+## Inspired By
+
+- [llm-wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) by Karpathy — the pattern
+- [obsidian-mind](https://github.com/sukbearai/obsidian-mind) — full-featured implementation for engineer performance tracking
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,155 @@
+# Codex-Vault
+
+> 给任何 LLM agent 加上持久记忆。
+> 你的笔记，你的 git，你的数据。
+
+## 问题
+
+LLM agent 每次对话都从零开始。上次做的决策忘了，讨论过的方案忘了，知识永远无法积累。
+
+## 方案
+
+一个结构化的知识库 + 3 个 hook，让 agent 拥有跨 session 的记忆。支持 **Claude Code** 和 **Codex CLI**。纯 markdown + git，没有外部依赖。
+
+## 核心用法
+
+5 个动作，覆盖日常全部场景：
+
+| 动作 | 怎么做 | 什么时候用 |
+|------|--------|-----------|
+| **设目标** | 编辑 `brain/North Star.md` | 首次使用，或方向调整时 |
+| **随手记** | `/dump 内容` | 做了决策、有了想法、完成了什么 — 随时 dump |
+| **查记忆** | `/recall 关键词` | 忘了之前的决策、想找历史笔记 |
+| **吃内容** | `/ingest URL或文件` | 看到好文章、拿到新资料，结构化存入 |
+| **收尾** | `/wrap-up` | session 结束前，检查质量、更新索引 |
+
+> Codex CLI 用 `$dump`、`$recall`、`$ingest`、`$wrap-up`。
+
+### 提示词模板
+
+直接复制使用，替换 `<>` 里的内容：
+
+**`/dump` — 随手记**
+```
+/dump 我们决定用 <方案A> 而不是 <方案B>，因为 <原因>
+/dump <项目名> 完成了，关键成果：<成果描述>
+/dump 今天发现一个规律：<规律描述>
+/dump 记住：<任何你想让 agent 下次记得的事>
+```
+
+**`/recall` — 查记忆**
+```
+/recall <关键词>
+/recall 我们之前怎么决定的 <某件事>
+/recall <项目名> 的进展
+```
+
+**`/ingest` — 吃内容**
+```
+/ingest <URL>
+/ingest sources/<文件名>.md
+```
+
+**`/wrap-up` — 收尾**
+```
+/wrap-up
+```
+> 不需要参数，agent 自动扫描本次 session 的变更。
+
+日常最高频的就是 `/dump`。其他按需使用。
+
+## 30 秒上手
+
+```bash
+# 在你的项目目录下：
+git clone https://github.com/sukbearai/codex-vault.git /tmp/codex-vault
+bash /tmp/codex-vault/plugin/install.sh   # 集成模式 — 自动安装 vault + hooks
+claude                                  # 或: codex
+```
+
+填好 `vault/brain/North Star.md`，开始对话。
+
+> **独立模式**：在 codex-vault 仓库内运行 `install.sh`，以 `vault/` 为工作目录。
+
+## 工作原理
+
+```
+你说话
+  ↓
+classify hook（分类：决策？进展？想法？）
+  ↓
+Agent 写笔记（按 instructions.md 规范）
+  ↓
+validate hook（检查：frontmatter？wikilinks？正确目录？）
+  ↓
+git commit（持久化）
+  ↓
+下次 session → session-start hook 注入上下文
+```
+
+三个 hook 驱动整个循环：
+
+| Hook | 触发时机 | 做什么 |
+|------|---------|--------|
+| **session-start** | Agent 启动 | 注入 North Star 目标、近期 git 变更、活跃项目、vault 文件清单 |
+| **classify-message** | 每条消息 | 检测决策、成果、项目更新 — 提示 agent 该归档到哪里 |
+| **validate-write** | 写 `.md` 后 | 检查 frontmatter 和 wikilinks — 在落盘前纠错 |
+
+## 支持的 Agent
+
+| Agent | Hooks | Skills | 状态 |
+|-------|-------|--------|------|
+| Claude Code | `.claude/settings.json` 3 hooks | `/dump` `/recall` `/ingest` `/wrap-up` | 完整支持 |
+| Codex CLI | `.codex/hooks.json` 3 hooks | `$dump` `$recall` `$ingest` `$wrap-up` | 完整支持 |
+| 其他 | 写适配器（[指南](docs/adding-an-agent.md)） | 取决于 agent | 社区贡献 |
+
+## Vault 结构
+
+```
+vault/
+  Home.md                 入口 — 当前焦点、快速链接
+  log.md                  操作日志（append-only）
+  brain/
+    North Star.md         目标和方向 — 每次 session 自动读取
+    Memories.md           记忆索引
+    Key Decisions.md      值得跨 session 记住的决策
+    Patterns.md           反复出现的规律
+  work/
+    Index.md              所有工作笔记的索引
+    active/               进行中的项目
+    archive/              已完成的项目
+  templates/              笔记模板
+  thinking/               草稿区 — 想清楚后归档，然后删除
+  sources/                原始资料 — 不可修改，agent 只读
+  reference/              问答回写 — 有价值的综合分析
+```
+
+八个目录，五种笔记类型。
+
+## 使用场景
+
+详见 [docs/usage.md](docs/usage.md) — 7 个真实场景，从首次安装到项目完成，每一步都有输入和输出示例。
+
+## 设计原则
+
+1. **数据主权** — 你的 markdown，你的 git，你的机器。没有云端锁定。
+2. **Agent 无关** — hook 是通用接口。一个 vault，多个 agent。
+3. **默认极简** — 3 个 hook，~100 行指令。按需增加复杂度。
+4. **图优先** — 目录按用途分组，`[[wikilinks]]` 按语义分组。链接是主要的组织工具。
+5. **面向未来** — 即使模型有了内建记忆，vault 仍然有价值：可审计、可迁移、git 追踪的本地存储。
+
+## 依赖
+
+- Git
+- Python 3
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 或 [Codex CLI](https://github.com/openai/codex)（二选一）
+- 可选：[Obsidian](https://obsidian.md)（图谱视图、反向链接、可视化浏览）
+
+## 灵感来源
+
+- [llm-wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) by Karpathy — 这个模式的起源
+- [obsidian-mind](https://github.com/sukbearai/obsidian-mind) — 面向工程师效能追踪的完整实现
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+const INSTALL_SH = path.join(PKG_ROOT, 'plugin', 'install.sh');
+const VERSION = fs.readFileSync(path.join(PKG_ROOT, 'plugin', 'VERSION'), 'utf8').trim();
+
+const args = process.argv.slice(2);
+const cmd = args[0] || 'init';
+
+switch (cmd) {
+  case '--version':
+  case '-v':
+    console.log(VERSION);
+    break;
+
+  case '--help':
+  case '-h':
+    printHelp();
+    break;
+
+  case 'init':
+    runInit();
+    break;
+
+  case 'upgrade':
+  case 'uninstall':
+    console.log(`"${cmd}" is coming in v0.2.0.`);
+    break;
+
+  default:
+    console.error(`Unknown command: ${cmd}\n`);
+    printHelp();
+    process.exit(1);
+}
+
+function printHelp() {
+  console.log(`codex-vault v${VERSION}
+
+Usage:
+  codex-vault init          Install vault into current directory (default)
+  codex-vault upgrade       Upgrade vault (coming in v0.2.0)
+  codex-vault uninstall     Remove vault  (coming in v0.2.0)
+  codex-vault -v, --version Print version
+  codex-vault -h, --help    Print this help`);
+}
+
+function runInit() {
+  // Check bash availability
+  const bashCheck = spawnSync('bash', ['--version'], { stdio: 'ignore' });
+  if (bashCheck.error) {
+    console.error('Error: bash is not available.');
+    console.error('On Windows, please install Git Bash or WSL.');
+    process.exit(1);
+  }
+
+  // Check if already installed
+  const versionFile = path.join(process.cwd(), 'vault', '.codex-vault', 'version');
+  if (fs.existsSync(versionFile)) {
+    const installed = fs.readFileSync(versionFile, 'utf8').trim();
+    console.log(`codex-vault v${installed} is already installed in this directory.`);
+    console.log('To reinstall, remove vault/.codex-vault/version first.');
+    return;
+  }
+
+  // Run install.sh
+  const result = spawnSync('bash', [INSTALL_SH], {
+    cwd: process.cwd(),
+    stdio: 'inherit',
+  });
+
+  if (result.error) {
+    console.error('Failed to run install.sh:', result.error.message);
+    process.exit(1);
+  }
+
+  if (result.status !== 0) {
+    process.exit(result.status);
+  }
+
+  // Write version file on success
+  const versionDir = path.dirname(versionFile);
+  fs.mkdirSync(versionDir, { recursive: true });
+  fs.writeFileSync(versionFile, VERSION + '\n');
+  console.log(`\ncodex-vault v${VERSION} installed successfully.`);
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@suwujs/codex-vault",
+  "version": "0.1.0",
+  "description": "Persistent knowledge vault for LLM agents (Claude Code, Codex CLI)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sukbearai/codex-vault"
+  },
+  "bin": {
+    "codex-vault": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "plugin/",
+    "vault/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "llm",
+    "knowledge-base",
+    "obsidian",
+    "vault"
+  ]
+}

package/plugin/VERSION

@@ -0,0 +1 @@
+0.1.0