vanar-neutron-memory

通过语义搜索保存和调用代理记忆。每个会话中持续存在的上下文。

# Neutron Memory

Every conversation, preference, and decision your agent makes can persist across sessions. Save what matters, and when you need it, semantic search finds the right context by meaning — not keywords. Every session builds on the last.

## How It Works

**Manual** — save and search with simple commands:
1. `./scripts/neutron-memory.sh save "user prefers dark mode" "Preferences"` — save context
2. `./scripts/neutron-memory.sh search "what theme does the user like"` — find it by meaning

**Automatic** (opt-in) — enable hooks to capture and recall automatically:
1. **Auto-Capture** saves conversations after each AI turn
2. **Auto-Recall** finds relevant memories before each AI turn and injects them as context

## Quick Start

See **[SETUP.md](SETUP.md)** for the full setup guide. TL;DR:

1. Get a free API key at **https://openclaw.vanarchain.com/** ($20 free credits, no credit card)
2. `export API_KEY=nk_your_key`
3. `./scripts/neutron-memory.sh test`

## Commands

### Save
```bash
./scripts/neutron-memory.sh save "Content to remember" "Title"
```

### Search
```bash
./scripts/neutron-memory.sh search "what do I know about X" 10 0.5
```

Arguments: `QUERY` `LIMIT` `THRESHOLD(0-1)`

### Diagnose
```bash
./scripts/neutron-memory.sh diagnose
```

Checks all prerequisites: curl, jq, API key, connectivity, and authentication.

## Hooks (Auto-Capture & Auto-Recall)

- `hooks/pre-tool-use.sh` — **Auto-Recall**: Queries memories before AI turn, injects relevant context
- `hooks/post-tool-use.sh` — **Auto-Capture**: Saves conversation after AI turn

Both are **disabled by default** (opt-in only). To enable:

```bash
export VANAR_AUTO_RECALL=true
export VANAR_AUTO_CAPTURE=true
```

## API Endpoints

- `POST /memory/save` — Save text (multipart/form-data)
- `POST /memory/search` — Semantic search (JSON body)

**Auth:** `Authorization: Bearer $API_KEY` — that's it. No other credentials needed.

## Security & Privacy

**No data is sent unless you run a command or explicitly enable auto-capture/auto-recall.** Both hooks are disabled by default.

This skill only sends data you explicitly save (or opt-in auto-captured conversations) to the Neutron API. Here's exactly what happens:

| Action | What's sent | Where |
|--------|------------|-------|
| **Save** | The text you pass to `save` or auto-captured conversation turns | `POST /memory/save` over HTTPS |
| **Search** | Your search query text | `POST /memory/search` over HTTPS |
| **Auto-Recall** | The user's latest message (used as search query) | `POST /memory/search` over HTTPS |
| **Auto-Capture** | `User: {message}\nAssistant: {response}` | `POST /memory/save` over HTTPS |

**What is NOT sent:**
- No local files are read or uploaded
- No environment variables (other than the API key for auth)
- No system information, file paths, or directory contents
- No data from other tools or skills

All communication is over HTTPS to `api-neutron.vanarchain.com`. The source code is fully readable in the `scripts/` and `hooks/` directories — three short bash scripts, no compiled binaries.

---

## 中文说明

# Neutron Memory

你的代理所进行的每一次对话、做出的每一项偏好和决策，都可以跨会话持久保存。保存重要内容，当你需要时，语义搜索会按含义而非关键词找到正确的上下文。每一个会话都建立在上一个之上。

## 工作原理

**手动模式** —— 使用简单命令进行保存和搜索：
1. `./scripts/neutron-memory.sh save "user prefers dark mode" "Preferences"` —— 保存上下文
2. `./scripts/neutron-memory.sh search "what theme does the user like"` —— 按含义查找

**自动模式**（需主动开启）—— 启用 hooks 以自动捕获和调用：
1. **Auto-Capture** 在每次 AI 回合后保存对话
2. **Auto-Recall** 在每次 AI 回合前查找相关记忆，并将其作为上下文注入

## 快速开始

完整设置指南请参阅 **[SETUP.md](SETUP.md)**。简要说明：

1. 在 **https://openclaw.vanarchain.com/** 获取免费 API 密钥（赠送 $20 额度，无需信用卡）
2. `export API_KEY=nk_your_key`
3. `./scripts/neutron-memory.sh test`

## 命令

### 保存
```bash
./scripts/neutron-memory.sh save "Content to remember" "Title"
```

### 搜索
```bash
./scripts/neutron-memory.sh search "what do I know about X" 10 0.5
```

参数：`QUERY` `LIMIT` `THRESHOLD(0-1)`

### 诊断
```bash
./scripts/neutron-memory.sh diagnose
```

检查所有前置条件：curl、jq、API 密钥、连通性和认证。

## Hooks（Auto-Capture 与 Auto-Recall）

- `hooks/pre-tool-use.sh` —— **Auto-Recall**：在 AI 回合前查询记忆，注入相关上下文
- `hooks/post-tool-use.sh` —— **Auto-Capture**：在 AI 回合后保存对话

两者**默认均禁用**（仅在主动开启时生效）。要启用：

```bash
export VANAR_AUTO_RECALL=true
export VANAR_AUTO_CAPTURE=true
```

## API 端点

- `POST /memory/save` —— 保存文本（multipart/form-data）
- `POST /memory/search` —— 语义搜索（JSON 请求体）

**认证：** `Authorization: Bearer $API_KEY` —— 仅此而已。无需其他凭据。

## 安全与隐私

**除非你运行命令或显式启用 auto-capture/auto-recall，否则不会发送任何数据。** 两个 hooks 默认均禁用。

此技能仅将你显式保存的数据（或主动开启后自动捕获的对话）发送到 Neutron API。具体过程如下：

| 操作 | 发送内容 | 发送目标 |
|--------|------------|-------|
| **Save** | 你传给 `save` 的文本或自动捕获的对话回合 | 通过 HTTPS 发送到 `POST /memory/save` |
| **Search** | 你的搜索查询文本 | 通过 HTTPS 发送到 `POST /memory/search` |
| **Auto-Recall** | 用户的最新消息（用作搜索查询） | 通过 HTTPS 发送到 `POST /memory/search` |
| **Auto-Capture** | `User: {message}\nAssistant: {response}` | 通过 HTTPS 发送到 `POST /memory/save` |

**不会发送的内容：**
- 不读取或上传任何本地文件
- 不发送任何环境变量（用于认证的 API 密钥除外）
- 不发送任何系统信息、文件路径或目录内容
- 不发送来自其他工具或技能的任何数据

所有通信均通过 HTTPS 发送到 `api-neutron.vanarchain.com`。源代码在 `scripts/` 和 `hooks/` 目录中完全可读 —— 三个简短的 bash 脚本，没有编译后的二进制文件。