Amber-Hunter Skill

Gives any AI client long-term memory — captures, encrypts, and recalls personal context across sessions Version: 1.2.30 | 2026-04-04

Tags: ai-memory | second-brain | local-encrypted | proactive-recall | cross-platform | context-management | RAG | long-term-memory | AI-personal-assistant | privacy-first

amber-hunter runs on the user's local machine (Mac / Linux / Windows). Local AI clients communicate via

localhost:18998

huper.org/api

What It Does

Amber-Hunter is the capture and recall layer of Huper琥珀 — a personal memory protocol that works across any AI client and any platform.

• AI long-term memory — gives ChatGPT, Claude, and any AI client persistent context across conversations
• Proactive capture — AI-initiated writes via

  /ingest

  ; user reviews and approves before memories are stored
• Instant recall —

  /recall?q=<query>

  retrieves relevant past memories before responding (hybrid semantic + keyword search)
• Second brain — builds a personal knowledge base that survives context windows and session boundaries
• E2E encrypted — AES-256-GCM, master_password in OS keychain, never uploaded in plaintext
• Cross-platform — macOS / Windows / Linux (desktop + headless server)
• Cloud sync — optional encrypted upload to huper.org for cross-device access
• RAG-ready —

  /recall

  endpoint returns structured context for Retrieval Augmented Generation pipelines

Memory Category System (v1.1.9+)

琥珀 uses a two-level taxonomy: category (8 fixed domains) + tags (specific labels).

The 8 Categories

thought

learning

decision

reflection

people

life

creative

dev

Auto-detection Keywords

The system auto-tags based on content keywords. AI clients should also suggest

category

/ingest

thought    → "想到", "突然想", "realize", "just thought"
learning   → "读了", "看了", "reading", "book says"
decision   → "决定", "选择了", "decided", "going with"
reflection → "反思", "复盘", "reflecting", "looking back"
people     → "和...聊", "talked to", "met with"
life       → "运动", "睡眠", "sleep", "exercise"
creative   → creative/design keywords
dev        → python/js/git/docker/api/sql/error keywords (all existing dev rules)

Multi-Client Integration Guide

Which endpoint to use

POST /ingest

POST /ingest

POST /ingest

POST https://huper.org/api/ingest

POST https://huper.org/api/ingest

Get the local API token

curl http://localhost:18998/token
# → {"api_key": "ahk_xxxx..."}

What's Worth Capturing — Judgment Rules

Use these rules when deciding whether to call

/ingest

Proactive Hook (v1.2.13):

handler.js/ts

agent:response

/ingest

review_required: true

Default behavior: when in doubt, set

review_required: true

Never capture: conversation scaffolding ("can you help me"), ephemeral context ("right now I need"), common knowledge, task details that won't recur.

API Endpoints (v1.2.9)

Core

/status

/

/token

/memories

Memory Retrieval

/recall

?q=<query>&limit=3&rerank=true&category_path=<path>&use_insights=true

0.4×keyword + 0.6×semantic

category_path

knowledge

knowledge/python

use_insights=true

/rerank

{query, memories[]}

{memories: [...]}

/recall/{id}/hit

/classify

?text=<text>

{"topics": "tag1,tag2"}

Memory Writes

/capsules

?limit=1-300

/capsules

/capsules/{id}

/capsules/{id}

/ingest

/extract

{text, source}

Queue Management

/queue

/queue/{id}/approve

/queue/{id}/reject

/queue/{id}/edit

/-review

/-review/{qid}

Session Context (proactive capture)

/freeze

/session/summary

/session/files

/session/preload

DID Identity (v1.2.20 — multi-device)

/did/setup

/did/status

/did/register-device

Sync & Config

/sync

/config

/config/llm

Localhost-only (security restricted)

/master-password

/bind-apikey

/ingest

Request Format

POST http://localhost:18998/ingest?token={api_key}
Content-Type: application/json

{
  "memo": "Anke prefers SQLite over Postgres for simpler deployment",
  "context": "During database selection discussion for amber project",
  "category": "decision",
  "tags": "decided,database",
  "source": "claude_cowork",
  "confidence": 0.9,
  "review_required": true,
  "agent_tag": "openclaw"    // v2.0.0: optional, adds #agent:openclaw tag for color-coding in UI
}

Response:

// Goes to review queue:
{"queued": true, "queue_id": "abc123", "category": "decision", "source_type": "ingest"}

// Written directly (confidence≥0.95 and review_required=false):
{"queued": false, "capsule_id": "xyz456", "category": "decision", "source_type": "ingest"}

// First ingest (capsule_count==0, v2.0.0):
{"queued": false, "capsule_id": "xyz456", "welcome": true, "message": "这是你的第一条记忆！...", "sample_count": 3}

LLM Provider Configuration (v1.2.1+)

amber-hunter supports multiple LLM providers:

minimax

openai

claude

local

# Set provider
curl -X PUT http://localhost:18998/config/llm?token={api_key} \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai"}'

# Get current provider
curl http://localhost:18998/config/llm?token={api_key}

Usage Patterns

openclaw / Claude Code

# 1. At conversation start — retrieve relevant context
TOKEN=$(curl -s http://localhost:18998/token | python3 -c "import sys,json; print(json.load(sys.stdin)['api_key'])")
curl "http://localhost:18998/recall?token=$TOKEN&q=YOUR_QUERY&limit=3"

# 2. During conversation — push a memory when something worth keeping surfaces
curl -X POST "http://localhost:18998/ingest?token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "memo": "User decided to use SQLite for simpler ops",
    "category": "decision",
    "tags": "decided",
    "source": "claude_code",
    "confidence": 0.9,
    "review_required": true
  }'

# 3. End of conversation — auto-extract 1-2 key takeaways (confidence=0.7)
curl -X POST "http://localhost:18998/ingest?token=$TOKEN" \
  -d '{"memo":"Summary: ...", "source":"claude_code", "confidence":0.7, "review_required":true}'

ChatGPT (via GPT Action / cloud API)

curl -X POST https://huper.org/api/ingest \
  -H "Authorization: Bearer USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memo": "User mentioned they prefer async Python patterns",
    "category": "dev",
    "tags": "python",
    "source": "chatgpt",
    "confidence": 0.8,
    "review_required": true
  }'

Platform Support

/freeze

Troubleshooting

# Service not running
curl http://localhost:18998/status
tail -f ~/.amber-hunter/amber-hunter.log

# Linux: secret-tool not found
sudo apt install libsecret-tools        # Ubuntu/Debian
sudo dnf install libsecret             # Fedora

# Check pending memories
curl "http://localhost:18998/queue?token=$(curl -s localhost:18998/token | python3 -c 'import sys,json;print(json.load(sys.stdin)[\"api_key\"])')"

FAQ & Known Issues

Q: amber-hunter runs on a VPS, not my local Mac. How do I configure the API key?

When amber-hunter is on a different machine than your browser, the dashboard's "Generate API Key" button can't auto-bind (it POSTs to

127.0.0.1:18998

Manual setup on the VPS:

# Option 1: environment variable (recommended for VPS)
echo 'export AMBER_TOKEN="your_api_key_here"' >> ~/.bashrc
source ~/.bashrc

# Option 2: write directly to config.json
mkdir -p ~/.amber-hunter
cat >> ~/.amber-hunter/config.json << 'EOF'
{"api_token": "your_api_key_here"}
EOF

# Then restart amber-hunter
launchctl unload ~/Library/LaunchAgents/com.huper.amber-hunter.plist
launchctl load ~/Library/LaunchAgents/com.huper.amber-hunter.plist

How to get the API key:

1. Go to huper.org → Dashboard → Account → API Key
2. Click "Generate API Key" and copy the key immediately (it's only shown once)

Q: Dashboard shows "尚未生成API Key" even after I generated one

This is a UI bug in older versions. Update to the latest version, or refresh the dashboard page. The key is stored correctly in the database — the display just wasn't updating after generation.

Q: Sync shows "network unreachable" or "Token 无效" errors

If amber-hunter is on a VPS: The

api_token

cat ~/.amber-hunter/config.json | grep api_token

If empty, the VPS can't reach huper.org cloud sync. Manually set the

api_token

If amber-hunter is on your local Mac: Make sure

bind-apikey

curl -s http://localhost:18998/config | python3 -c "import sys,json; d=json.load(sys.stdin); print('api_token:', d.get('api_key','(not set)')[:10]+'...')"

Q: I generated a new API Key but amber-hunter on VPS stopped syncing

Each key can only be used by one amber-hunter instance at a time. If you generate a new key from the dashboard, the old key (still configured on VPS) becomes invalid. Either:

• Copy the new key to the VPS config and restart
• Or keep using the old key (don't click "Generate New Key" unless you mean to rotate it)

Q: "尚未生成API Key" never goes away on first use

This means you haven't generated an API key yet. Click the orange "生成 API Key" button on the Dashboard → Account → API Key page. The key is shown once — copy it immediately and save it somewhere before leaving the page.

Version History

• v1.2.29 (2026-04-04): G1 Self-Correction Loop —

  correction_log

  SQLite 表记录每次校正事件；

  _normalize_tag

  应用用户校正规则（5分钟缓存）；

  record_tag_correction

  /

  record_category_correction

  在 queue edit 时调用；

  GET /corrections/stats

  分析校正模式；

  POST /corrections/apply

  采纳替换规则。
• v1.2.28 (2026-04-04): P2-1 Mem0 Auto-extraction —

  core/extractor.py

  从对话自动抽取 facts/preferences/decisions；

  POST /extract/auto

  高置信直接入库/中置信进队列；

  GET /extract/status

  查看抽取统计；结合 WAL 信号 + 偏好提取 + LLM 结构化抽取三重机制。
• v1.2.27 (2026-04-04): P1-1 Structured User Profile —

  user_profile

  SQLite 表；

  core/profile.py

  LLM extraction；

  GET /profile

  返回四段画像；

  PUT /profile/{section}

  手动更新；

  POST /profile/build

  从 session 构建；recall 响应注入

  profile

  字段。
• v1.2.26 (2026-04-04): P0-2续 WAL GC —

  wal_gc(age_hours=24)

  删除已处理条目；

  get_wal_stats()

  新增

  processed_count

  ；懒 GC（>50 条已处理时自动清理）；

  POST /wal/gc

  端点支持手动 GC。
• v1.2.25 (2026-04-04): P0-3 可解释召回 —

  _kw_score

  返回

  (score, matched_terms)

  ；

  breakdown

  新增

  matched_terms

  +

  wal_signal

  ；

  reason

  改为详细自然语言说明（含具体匹配词、语义相似度%、WAL信号类型）。
• v1.2.24 (2026-04-04): P0-2 WAL 热存储 —

  core/wal.py

  新增 Session State WAL 模块；

  recall_memories

  返回前检测偏好/决定/修正信号并写入

  ~/.amber-hunter/session_wal.jsonl

  ；新增

  /wal/status

  +

  /wal/entries

  端点。
• v1.2.23 (2026-04-04): P0-1 LanceDB 向量搜索 —

  core/vector.py

  新增 LanceDB 封装；胶囊入库时同步写向量；recall 优先 LanceDB top_k 检索（0.50权重），on-the-fly 回退；升级 torch 2.8.0。
• v1.2.22 (2026-04-04): Fix line 1570 bug (

  row[2]

  →

  stored_challenge

  ) in

  /api/did/auth/verify

  ; add

  POST /did/auth/challenge

  +

  POST /did/auth/sign-challenge

  in amber_hunter; fix

  did_register_device

  to use

  get_api_token()

  ; fix

  HOME

  reference before definition.
• v1.2.21 (2026-04-04): D2 DID Challenge-Response Auth + capsule key derivation —

  derive_capsule_key

  wired into

  create_capsule

  /

  get_capsule

  (DID device key → AES-256-GCM, PBKDF2 fallback);

  POST /api/did/auth/challenge

  +

  POST /api/did/auth/verify

  endpoints;

  require_auth

  supports DID token;

  device_priv

  saved to

  did.json

  .
• v1.2.8 (2026-04-01): Fix proactive-check.js — filter log lines from session transcript; memo truncation 60→80 chars.
• v1.2.4 (2026-04-01): Fix

  source_type

  /

  category

  missing in sync payload;

  httpx.Client

  reuse for sync;

  /capsules

  limit param;

  /memories

  new fields.
• v1.2.3 (2026-04-01): Fix

  /recall

  semantic search on full corpus; hybrid mode

  0.4×keyword + 0.6×semantic

  ;

  /status

  enhanced with capsule_count/queue_pending/last_sync.
• v1.2.1 (2026-03-31): LLM abstraction layer (

  core/llm.py

  );

  /rerank

  endpoint;

  /classify

  LLM fallback; proactive session selection by message count.
• v1.1.9 (2026-03-31): Universal memory taxonomy (8 life categories);

  /ingest

  + queue management;

  source_type

  +

  category

  fields; ChatGPT GPT Action.
• v0.9.5 (2026-03-28): amber-proactive V4 — self-contained cron, LLM extraction.
• v0.8.4 (2026-03-22): E2E encryption, cross-platform keychain,

  /memories

  no-auth.

Built with 🔒 by Anke Chen for the Huper琥珀 ecosystem.