Ai好记

Use the Ai好记 Agent Open Platform to query, read, export, and organize user notes. For actual endpoints, fields, and use-case details, see

references/agent-open-platform.md

; this reference must be read when handling writes, record retrieval, exports, automatic classification, or when API parameters are uncertain.

Trigger Boundaries

Route requests according to the following priority:

When the user explicitly specifies that the target is in local files, a code repository, Obsidian, Notion, Youdao Note, or another service, follow the specified carrier and do not trigger this Skill.
When no carrier is specified and the request concerns personal notes, personal notebooks, or note details supported by this Skill, trigger Ai好记 by default. This refers to the user’s external personal note library, not Agent or Claude memory, and the user does not need to mention “Ai好记,” “AI好记,” or
```
aihaoji
```
.
Broad terms such as
```
notes
```
,
```
folder
```
, records, files, or content are not sufficient on their own. Source code, tests, API fields, and local-file contexts do not indicate a personal-note intent.

The positive scope includes querying, searching, exporting, creating blank notes, organizing, moving, and automatically classifying notes; managing notebooks; and viewing summaries, outlines, full text, original text, polished versions, highlights, annotations, My Records, and AI Highlights. Exporting personal notes to Markdown still falls within this Skill; creating notes uses Markdown directly; creating, reading, or modifying a local Markdown file does not fall within this Skill.

Routing to this Skill does not authorize writes. Before creating, renaming, moving, deleting, or automatically classifying anything, first perform read-only queries to obtain the real IDs, present a change plan, and wait for explicit confirmation. Do not call write endpoints before confirmation. Deleting a notebook still requires separate confirmation.

Configuration

Prefer reading from

~/.aihaoji/config.json

json

{
  "apiKey": "sk-sxxxxxxxx",
  "baseUrl": "https://openapi.aihaoji.com"
}

If it is missing, then read

$AIHAOJI_API_KEY

and

$AIHAOJI_BASE_URL

. The request header is always:

text

Authorization: $AIHAOJI_API_KEY

When no API Key is available, guide the user to

https://openapi.aihaoji.com

to create an

sk-s...

developer key. The user may provide the Key directly in chat, in which case the current Agent validates it and writes it to the shared configuration. If the

aihaoji-skills

CLI is installed locally, the user may also run

aihaoji-skills setup

. After obtaining the Key, first validate it by calling

GET /agent-open/api/v1/auth/verify

, then write it to

~/.aihaoji/config.json

with

permissions. If automatic configuration fails, prompt the user to use an available configuration entry point.

Host Installation Locations

For cross-platform installation, use

~/.agents/skills/aihaoji

as the global master copy and do not duplicate separate content for every host:

Host	Read Location	Description
Codex	`~/.agents/skills/aihaoji`	Latest official user-level Skill directory
OpenClaw	`~/.agents/skills/aihaoji`	personal-agent source; takes priority over `~/.openclaw/skills`
Claude Code	`~/.claude/skills/aihaoji`	Symlink to `~/.agents/skills/aihaoji`
Hermes Agent	`~/.agents/skills/aihaoji`	Enabled through `skills.external_dirs` in `~/.hermes/config.yaml`

Hermes Agent configuration:

yaml

skills:
  external_dirs:
    - ~/.agents/skills

~/.aihaoji/config.json

is the shared machine-level Key configuration for Codex, OpenClaw, Claude Code, and Hermes Agent, and does not belong to any host’s Skill directory. Users may provide the Key directly in chat, in which case the current AI writes it to this file. Keep the file permissions at

after writing. Claude Desktop and Claude Code use different Skill-loading mechanisms; the Claude path above applies to Claude Code.

Installation and Configuration Entry Points

Cross-platform Skill installation: run
```
npx skills add AiHaoJi-Agent/aihaoji-skills -g
```
. This installs the Skill into the user-level directory. Codex and OpenClaw read
```
~/.agents/skills/aihaoji
```
, Claude Code uses
```
~/.claude/skills/aihaoji
```
, and Hermes Agent reads the shared directory through
```
external_dirs
```
.
Key configuration: preferably, the current Agent validates the Key and writes it to the shared configuration. If the
```
aihaoji-skills
```
CLI is installed locally, the user may run
```
aihaoji-skills setup
```
.

Hermes Agent uses

skills.external_dirs

for this repository. Do not keep multiple copies with the same name, as this may cause a host to load an outdated version.

Mandatory Rules

When the user wants to query, view, find, or organize Ai好记 notes, the Open Platform endpoints must be called. Do not scan local directories, logs, caches, or source code to guess note content.
Every internal ID must come from an API response and must never be written manually.
```
folder_id
```
,
```
target_folder_id
```
,
```
note_id
```
, and
```
move_item_list[].item_id
```
must first be queried and confirmed.
Hide
```
note_id
```
,
```
folder_id
```
,
```
user_id
```
, and
```
key_id
```
during normal display. Show them only when the user requests debugging information or raw fields.
If an endpoint reports an error, times out, or returns
```
401/403/429/5xx
```
, clearly state that data cannot currently be obtained through the Ai好记 Open Platform. Do not fall back to a local search.
Before every write, present the change plan and wait for user confirmation. Deleting a notebook requires separate confirmation and must not be included in the default automatic-organization plan.

Parameter Sources

Parameter	Source
`folder_id`	Real notebook ID returned by `GET /agent-open/api/v1/folders`
`parent_id`	For a new sub-notebook, use the real parent `folder_id` ; for a top-level notebook, pass `parent_id=0` , not `null`
`target_folder_id`	Target notebook ID for moving one or multiple notes, also used when bulk-moving notebooks; must be a real notebook ID; use `-1` to move a notebook to the root directory
`note_id`	Real note ID returned by `GET /agent-open/api/v1/notes` or a details endpoint
`move_item_list`	Same structure as the PC move endpoint: notes use `move_type=1` , notebooks use `move_type=2` , and `item_id` is the real ID
`name`	Explicit user input, or an AI-generated automatic-classification plan that has been confirmed by the user
`include_records`	Set to `true` when the user wants highlights, annotations, or My Records, or when classification requires annotation evidence
`include_export_markdown`	Set to `true` when the user selects exporting Markdown to the local system

Common Endpoints

Intent	Endpoint
Verify Key	`GET /agent-open/api/v1/auth/verify`
Notebook tree	`GET /agent-open/api/v1/folders`
Note list / search / recent notes	`GET /agent-open/api/v1/notes`
Note details / semantic view / export / highlights, annotations, and My Records	`GET /agent-open/api/v1/notes/{note_id}`
Create notebook	`POST /agent-open/api/v1/folders`
Rename notebook	`PUT /agent-open/api/v1/folders/{folder_id}`
Delete notebook	`DELETE /agent-open/api/v1/folders/{folder_id}`
Create blank note	`POST /agent-open/api/v1/notes` , with `title` , `content_markdown` , and optional `folder_id` in the request body
Move a single note	`PATCH /agent-open/api/v1/notes/{note_id}/folder` , with `target_folder_id` in the request body
Bulk-move notes	`POST /agent-open/api/v1/notes/batch-move`
Bulk-move notebooks	`POST /agent-open/api/v1/folders/batch-move`

Reading the notebook tree requires

folder:list

; creating a blank note requires

note:create

; other write permissions generally require

folder:write

note:move

; reading records requires

note:read

Intent Routing

List notebooks: first call
```
GET /agent-open/api/v1/folders
```
, then display the actual hierarchy from the endpoint’s
```
folder_tree_text
```
or
```
children
```
.
View notes in a notebook: first use
```
/folders
```
to locate the real
```
folder_id
```
, then call
```
/notes?folder_id=...
```
; do not reuse the notebook name as
```
keyword
```
.
Search for a keyword within a notebook: first locate
```
folder_id
```
, then call
```
/notes?folder_id=...&keyword=...
```
; use the number of results returned by the API without applying an additional manual reduction.
Find the most recent N notes: use
```
/notes?page_no=1&page_size=N&sort_mode=create_time&sort_order=desc
```
; if N is not specified, default to 10.
Find the oldest N notes: use
```
sort_order=asc
```
; if N is not specified, default to 10.
Find a note by URL: search using the complete URL as
```
keyword
```
and prioritize matching the real URL in the returned results.
View a summary, outline, or highlights overview: pass
```
semantic_view=summary|outline|highlights
```
to the details endpoint.

View full text, original text, or a polished version: first ask

A: Export as a Markdown file to the local system

B: View directly in the chat

. For A, use

include_export_markdown=true

; for B, view it in chunks using

semantic_chunk_no

View highlights, annotations, or My Records: call the details endpoint with

include_records=true

; focus on

data.records_detail.records

data.records_detail.my_record

data.records_detail.ai_highlights

, and

data.records_detail.ai_highlights_status

Create a blank note: first ask for and confirm the title, target notebook, and Markdown body summary, then call
```
POST /agent-open/api/v1/notes
```
. After creation succeeds, use the returned
```
note_id
```
to call the details endpoint with
```
semantic_view=full
```
and verify the result by reading it back.

Organization and Writes

The required write sequence is:

Read
```
folders
```
and
```
notes
```
to confirm the real IDs.
Read note details and any necessary record information.
Present a plan containing the notebooks to create, notes or notebooks to move, target locations, and classification rationale.
Wait for explicit user confirmation.
Create missing notebooks, then move the notes or notebooks.
Re-query the target notebook or note list to verify the result.

Initial boundaries for creating blank notes: create one note at a time;

content_markdown

is required and may contain at most 100000 characters. Safe Markdown such as headings, bold text, lists, tables, links, and code is supported. Do not pass unrestricted HTML. Attachments, image uploads, @ references, editing, appending, deleting, and bulk creation are not supported.

When creating a top-level notebook, the request body must use

"parent_id": 0

. The backend normalizes

to the root-level

parent_id=None

; do not send JSON

null

, because the production endpoint may return a “Failed to create notebook” error.

Requirements for automatic classification and organization:

AI-powered automatic classification must first read the note content and record evidence. Do not bulk-move notes based only on their titles unless the user explicitly requests rough organization.
Reuse an existing notebook with the same name instead of creating a duplicate.
List notes with uncertain destinations as “Pending confirmation”; do not force them into a destination.
Do not delete notebooks during the same automatic-organization run.

Prefer the same parameters as the PC endpoint for bulk-move requests:

json

{
  "target_folder_id": 123,
  "move_item_list": [
    {"move_type": 1, "item_id": "task_xxx", "pre_id": null}
  ]
}

When moving notebooks, use

move_type=2

. A

target_folder_id=-1

value moves the notebook to the root directory.

Error Handling

```
401/403
```
: Explain that the API Key may be invalid, expired, disabled, deleted, unauthorized, associated with a non-member account, or no longer bound to the application.
Insufficient permissions: Identify the required permission:
```
note:list
```
,
```
note:read
```
,
```
note:create
```
,
```
folder:list
```
,
```
folder:write
```
, or
```
note:move
```
.
```
404
```
: Explain that the note or notebook does not exist, then re-query the candidates and ask the user to confirm.
```
429
```
: Explain that the rate limit was triggered and suggest trying again later or reducing the batch size.

Reference

Detailed API information, fields, record structures, export rules, and scenario wording:
```
references/agent-open-platform.md
```

aihaoji

NPX Install

Tags

SKILL.md Content (Chinese)