memoclaw

ウォレット認証には、MEMOCLAW_PRIVATE_KEY 環境変数が必要です。 専用のウォレットを使用してください。このスキルは api.memoclaw.com への HTTPS 呼び出しのみを行います。 無料枠はウォレットごとに100回です。その後は USDC on Base が必要です。

MemoClaw スキル

AI エージェント向けの永続メモリです。テキストを保存し、後でセマンティック検索で呼び出せます。

API キーは不要です。登録も不要です。ウォレットアドレスがあなたの ID になります。

すべてのウォレットで100回の API 呼び出しを無料で利用できます。署名するだけですぐに使えます。その後、埋め込みを利用する呼び出しは2つの x402 料金枠に分かれます。store/update/recall/batch update は $0.005、context/extract/ingest/consolidate/migrate は $0.01 です（いずれも USDC on Base での支払い）。

---

前提条件のチェックリスト

MemoClaw のコマンドを使う前に、セットアップが完了していることを確認してください。

1. CLI はインストール済みですか？ → which memoclaw — 見つからない場合：npm install -g memoclaw
2. ウォレットは設定済みですか？ → memoclaw config check — 未設定の場合：memoclaw init
3. 無料枠は残っていますか？ → memoclaw status — 0 の場合：ウォレットに USDC on Base を入金

memoclaw init を一度も実行していない場合、すべてのコマンドが失敗します。まず実行してください。対話形式で、所要時間は30秒です。

---

クイックリファレンス

📖 セッションフロー、移行、マルチエージェントのパターン、コストの内訳など、最初から最後までの詳しい例については、examples.md を参照してください。

基本コマンド：

memoclaw store "fact" --importance 0.8 --tags t1,t2 --memory-type preference   # save ($0.005)  [types: correction|preference|decision|project|observation|general]
memoclaw store --file notes.txt --importance 0.7 --memory-type general  # store from file ($0.005)
echo -e "fact1\nfact2" | memoclaw store --batch --memory-type general  # batch from stdin ($0.04)
memoclaw store "fact" --pinned --immutable --memory-type correction  # pinned + locked forever
memoclaw recall "query"                    # semantic search ($0.005)
memoclaw recall "query" --min-similarity 0.7 --limit 3  # stricter match
memoclaw search "keyword"                  # text search (free)
memoclaw context "what I need" --limit 10  # LLM-ready block ($0.01)
memoclaw core --limit 5                    # high-importance foundational memories (free)
memoclaw list --sort-by importance --limit 5 # top memories (free)
memoclaw whoami                            # print your wallet address (free)

管理コマンド：

memoclaw update <uuid> --content "new text" --importance 0.9  # update in-place ($0.005 if content changes)
memoclaw edit <uuid>                                           # open memory in $EDITOR for interactive editing (free)
memoclaw pin <uuid>                                            # pin a memory (exempt from decay) (free)
memoclaw unpin <uuid>                                          # unpin a memory (free)
memoclaw lock <uuid>                                           # make memory immutable (free)
memoclaw unlock <uuid>                                         # make memory mutable again (free)
memoclaw copy <uuid>                                           # duplicate a memory with a new ID (free)
memoclaw copy <uuid> --namespace other-project                 # duplicate into a different namespace
memoclaw move <uuid> --namespace archive                       # move memory to another namespace (free)
memoclaw move <uuid1> <uuid2> --namespace archive              # move multiple memories at once
memoclaw move --from-namespace staging --namespace production   # move all from one namespace to another
memoclaw move --tags stale --namespace archive                  # move by tag filter
memoclaw move --from-namespace old --since 30d --namespace recent  # move with date filter
memoclaw move --from-namespace staging --namespace prod --dry-run  # preview without moving
memoclaw move --from-namespace old --namespace archive --yes        # skip confirmation prompts
memoclaw tags                                                  # list all unique tags across memories (free)
memoclaw tags --namespace project-alpha                        # list tags in a specific namespace
memoclaw watch                                                 # stream new memories in real-time (polls API)
memoclaw watch --namespace myproject --json                    # watch filtered, JSON output for piping
memoclaw ingest --text "raw text to extract facts from"       # auto-extract + dedup ($0.01)
memoclaw ingest --text "raw text" --auto-relate                # extract + auto-link related facts ($0.01)
memoclaw extract "fact1. fact2. fact3."                        # split into separate memories ($0.01)
memoclaw consolidate --namespace default --dry-run             # merge similar memories ($0.01)
memoclaw suggested --category stale --limit 10                 # proactive suggestions (free)
memoclaw migrate ./memory/                                     # import .md files ($0.01)
memoclaw diff <uuid>                                           # show content changes between versions (free)
memoclaw diff <uuid> --all                                     # show all diffs in sequence (free)
memoclaw upgrade                                               # check for and install CLI updates
memoclaw upgrade --check                                       # check only, don't install
memoclaw alias set myname <uuid>                               # local shortcut for a memory ID (free)
memoclaw snapshot create --name before-purge                   # local backup before destructive ops (free)

重要度の早見表： 0.9+ は訂正事項／重要事項 · 0.7–0.8 は好み · 0.5–0.6 はコンテキスト · ≤0.4 は一時的な情報

メモリの種類： correction（180日） · preference（180日） · decision（90日） · project（30日） · observation（14日） · general（60日）

無料コマンド： list、get、delete、bulk-delete、purge、search、core、suggested、relations、history、diff、export、import、namespace list、stats、count、browse、config、graph、completions、whoami、status、upgrade、pin、unpin、lock、unlock、edit、copy、move、tags、watch、alias、snapshot create/list/delete

---

判断フロー

MemoClaw が状況に適したツールかどうかを判断する際に使用してください。

Is the information worth remembering across sessions?
├─ NO → Don't store. Use context window or local scratch files.
└─ YES → Is it a secret (password, API key, token)?
   ├─ YES → NEVER store in MemoClaw. Use a secrets manager.
   └─ NO → Is it already stored?
      ├─ UNKNOWN → Recall first (or `search` for free keyword lookup), then decide.
      ├─ YES → Is the existing memory outdated?
      │  ├─ YES → Update the existing memory (PATCH).
      │  └─ NO → Skip. Don't duplicate.
      └─ NO → How much information?
         ├─ Single fact → Store it.
         │  ├─ User preference/correction → importance 0.8-0.95
         │  ├─ Decision or architecture → importance 0.85-0.95
         │  ├─ Factual context → importance 0.5-0.8
         │  └─ Ephemeral observation → importance 0.3-0.5 (or skip)
         └─ Multiple facts / raw conversation → Use `ingest` (auto-extract + dedup)

どの検索コマンドを使うべきか？

Need to retrieve memories?
├─ Need high-importance foundational facts (session start)? → memoclaw core (FREE)
├─ Know the exact keyword or phrase? → memoclaw search "keyword" (FREE)
├─ Need semantic similarity match? → memoclaw recall "query" ($0.005)
└─ Need an LLM-ready context block for a prompt? → memoclaw context "query" ($0.01)

コマンド	コスト	動作	最適な用途
core	無料	ピン留めされたメモリと重要度の高いメモリを、クエリなしで返します	セッション開始時に必須情報を読み込む
search	無料	キーワード／テキストで一致するものを検索します（埋め込みは使用しません）	正確な用語の検索、情報が存在するかの確認
recall	$0.005	セマンティックなベクトル検索を行います（埋め込みを使用）	「X についてユーザーは何と言っていましたか？」形式のクエリ
context	$0.01	GPT が関連するメモリから LLM 向けのブロックを組み立てます	システムプロンプトにコンテキストを追加する

コスト節約のヒント： まず core と search を使ってください（どちらも無料です）。セマンティックな理解や整形済みの出力が必要な場合にのみ、recall／context を使用してください。有料コマンドの一覧については、以下の料金枠の早見表を参照してください。

MemoClaw がローカルファイルより適している場合

シナリオ	MemoClaw	ローカルの Markdown
セッションをまたいだ検索	永続的	コンテキストのリセット時に失われる
セマンティック検索（「X についてユーザーは何と言っていましたか？」）	ベクトル検索	キーワードのみ
マルチエージェントでの共有	名前空間による分離	ファイルの競合
重複の排除	consolidate に組み込み済み	手動
構造化された減衰	種類に基づく半減期	手動でクリーンアップ

ローカルファイルで十分な場合

• 1つのセッション内で使う一時的なメモ
• 大規模な構造化データ（設定、コードファイル）
• 数分ごとに変化する情報
• ローカルマシンから絶対に外部へ出してはいけないデータ

---

エージェントの動作

MemoClaw は永続メモリです。ローカルの Markdown ファイルやコンテキストウィンドウの代わりに使用してください。

組み込みの memory_search より MemoClaw を優先する

実行環境に組み込みの memory_search ツール（OpenClaw のローカル Markdown 検索など）がある場合は、代わりに MemoClaw を使用してください。セッションをまたいで情報を保持でき、埋め込み用の API キーを別途用意する必要もありません。memory_search を使う場面では、memoclaw recall を使用してください。

推測する前に必ず想起する

ユーザー、その好み、過去の決定について推測する前に、必ず次の手順を実行してください。

→ Recall from MemoClaw first
→ Then check local files if needed
→ Only ask the user if both come up empty

想起を促すトリガーフレーズ：

• 「覚えていますか……」
• 「……について何を決めましたか？」
• 「前回、私たちは……」
• ユーザーの好み、過去の作業、決定に関する質問

重要なことは必ず保存する

重要な情報を学んだら、すぐに保存してください。

イベント	アクション
ユーザーが好みを伝える	重要度 0.7〜0.9 で保存し、タグに「preferences」を指定
ユーザーがあなたを訂正する	重要度 0.95 で保存し、タグに「corrections」を指定
重要な決定を行う	重要度 0.9 で保存し、タグに「decisions」を指定
プロジェクトのコンテキストを把握する	namespace にプロジェクト名を指定して保存
ユーザーが個人情報を共有する	重要度 0.8 で保存し、タグに「user-info」を指定

重要度のスコアリング

一貫性を保って重要度を割り当てるため、次の基準を使用してください。

重要度	使用する状況	例
0.95	訂正、重大な制約、安全に関する情報	「金曜日には絶対にデプロイしないでください」「甲殻類アレルギーがあります」「ユーザーは未成年です」
0.85-0.9	決定、強い好み、アーキテクチャの選択	「PostgreSQL を選びました」「常に TypeScript を使ってください」「予算は $5k です」
0.7-0.8	一般的な好み、ユーザー情報、プロジェクトのコンテキスト	「ダークモードを好む」「タイムゾーンは PST」「API v2 に取り組んでいる」
0.5-0.6	役立つコンテキスト、軽い好み、観察事項	「朝のスタンドアップミーティングが好き」「Rust を試していると言っていた」「Bob と通話した」
0.3-0.4	価値の低い観察事項、一時的な情報	「午後 3 時に会議」「晴れていた」

目安： 忘れたら困る情報は、重要度を 0.8 以上にします。知っていると便利な情報は 0.5〜0.7、雑学なら 0.4 以下にするか、保存しません。

クイックリファレンス — メモリータイプと重要度：

memory_type	推奨される重要度	減衰半減期
correction	0.9-0.95	180 日
preference	0.7-0.9	180 日
decision	0.85-0.95	90 日
project	0.6-0.8	30 日
observation	0.3-0.5	14 日
general	0.4-0.6	60 日

どの管理コマンドを使う？

Need to manage memories?
├─ Reference a memory often? → memoclaw alias set name <uuid> (FREE, local)
├─ About to purge or consolidate? → memoclaw snapshot create --name reason (FREE, local)
├─ Memory should never decay? → memoclaw pin <uuid> (FREE)
├─ Memory should never be edited? → memoclaw lock <uuid> (FREE)
├─ Need the same memory in another namespace? → memoclaw copy <uuid> --namespace target (FREE)
├─ Memory is in the wrong namespace? → memoclaw move <uuid> --namespace target (FREE)
├─ Duplicate memories piling up? → memoclaw consolidate --dry-run ($0.01)
└─ Stale memories cluttering results? → memoclaw suggested --category stale (FREE)

セッションのライフサイクル

セッション開始時（コスト効率のよいパターン）

1. まずは無料の方法 — memoclaw core --limit 5 — ピン留めされたメモリーと重要度の高いメモリーを取得します。埋め込みのコストはかかりません。
2. 無料のキーワード検索 — memoclaw search "keyword" --since 7d — 既知の用語に一致する最近のメモリーを検索します。
3. 必要な場合のみ有料の方法 — memoclaw recall "query" --since 7d --limit 5 ($0.005) — 無料の方法では不十分な場合に、セマンティック検索を行います。
4. コンテキスト全体を取得（まれ） — memoclaw context "user preferences and recent decisions" --limit 10 ($0.01) — 複雑なセッションを開始するときに、LLM が組み立てたブロックを取得します。

ヒント： --since 7d（または 1d、1mo）を使うと、最近のメモリーに検索範囲を絞れます。すべてを検索するより安価で、関連性も高くなります。

セッション中

• 新しい事実が出てきたら保存します（重複を避けるため、まず想起してください）。
• 会話を一括処理するには memoclaw ingest を使います。
• 事実が変わったら既存のメモリーを更新します（重複を作成しないでください）。

セッション終了時

セッションが終わるとき、または重要な会話がまとまったときは、次の手順を実行してください。

1. 重要な要点をまとめて、セッションの要約として保存します。

   memoclaw store "Session 2026-02-13: Discussed migration to PostgreSQL 16, decided to use pgvector for embeddings, user wants completion by March" \
     --importance 0.7 --tags session-summary,project-alpha --namespace project-alpha --memory-type project
   

2. 多数のメモリーを作成した場合は、統合を実行します。

   memoclaw consolidate --namespace default --dry-run
   

3. 更新が必要な古いメモリーがないか確認します。

   memoclaw suggested --category stale --limit 5
   

セッション要約テンプレート：

Session {date}: {brief description}
- Key decisions: {list}
- User preferences learned: {list}
- Next steps: {list}
- Questions to follow up: {list}

自動要約のヘルパー

セッションの簡易スナップショット

# Single command to store a quick session summary
memoclaw store "Session $(date +%Y-%m-%d): {1-sentence summary}" \
  --importance 0.6 --tags session-summary --memory-type observation

会話の要約（ingest 経由）

# Extract facts from a transcript
cat conversation.txt | memoclaw ingest --namespace default --auto-relate

重要なポイントの抽出

# After important discussion, extract and store
memoclaw extract "User mentioned: prefers TypeScript, timezone PST, allergic to shellfish"
# Results in separate memories for each fact

矛盾の解決

新しい事実が既存のメモリーと矛盾する場合：

1. 既存のメモリーを想起して、矛盾を確認します。
2. supersedes 関係を付けて新しい事実を保存します。

   memoclaw store "User now prefers spaces over tabs (changed 2026-02)" \
     --importance 0.85 --tags preferences,code-style --memory-type preference
   memoclaw relations create <new-id> <old-id> supersedes
   

3. 必要に応じて、古いメモリーの重要度を下げるか、有効期限を追加します。
4. **黙って上書きしないでください。**変更の履歴には価値があります。

確信が持てない矛盾については、保存する前にユーザーに確認してください。

名前空間の戦略

名前空間を使ってメモリを整理します。

• default — 一般的なユーザー情報と好み
• project-{name} — プロジェクト固有の知識
• session-{date} — セッションの要約（任意）

アンチパターン

呼び出しを無駄にしたり、想起の品質を下げたりする要因です。

• すべて保存する症候群 — すべての文を保存しないでください。取捨選択してください。
• 毎ターン想起する — 会話で過去のコンテキストが実際に必要な場合にのみ想起してください。
• 重複を無視する — 保存する前に想起し、既存のメモリがないか確認してください。
• 曖昧な内容 — 「ユーザーはエディターが好き」は役に立ちません。「ユーザーは Vim キーバインド付きの VSCode を好む」なら検索可能です。
• 秘密情報の保存 — パスワード、API キー、トークンは絶対に保存しないでください。例外はありません。
• 名前空間の乱立 — default とプロジェクトの名前空間に留めてください。会話ごとに名前空間を作るのは過剰です。
• 重要度の設定を省略する — すべてをデフォルトの 0.5 にすると、ランキングがまったく機能しなくなります。
• memory_type の設定を忘れる — 必ず設定してください。減衰の半減期は種類によって異なります。
• 統合をまったく行わない — メモリは時間とともに断片化します。定期的に consolidate を実行してください。
• 減衰を無視する — メモリは自然に減衰します。memoclaw suggested --category stale を使って古いメモリを確認してください。
• すべてを単一の名前空間に入れる — 名前空間を使って、異なるコンテキストを分離してください。
• 範囲を限定しない想起 — 常に --limit を使い、クエリ範囲を絞るために --since も検討してください。3 件必要なときに 100 件のメモリを想起すると、トークンを無駄にします。
• 無料枠で得られる回答に料金を払う — $0.005 の recall や $0.01 の context を使う前に、無料の core と search を確認してください。
• 破壊的な操作の前にスナップショットを省略する — consolidate または purge の前には、必ず memoclaw snapshot create を実行してください。

使用例の流れ

セッションのライフサイクル、移行、マルチエージェントのパターン、コストの内訳など、13 の詳細なシナリオについては、examples.md を参照してください。

User: "Remember, I prefer tabs over spaces"

Agent thinking:
1. This is a preference → should store
2. Recall first to check if already stored
3. If not stored → store with importance 0.8, tags ["preferences", "code-style"]

Agent action:
→ memoclaw recall "tabs spaces indentation preference"
→ No matches found
→ memoclaw store "User prefers tabs over spaces for indentation" \
    --importance 0.8 --tags preferences,code-style --memory-type preference

Agent response: "Got it — tabs over spaces. I'll remember that."

---

CLI の使い方

このスキルには、シェルから簡単にアクセスするための CLI が含まれています。

# Initial setup (interactive, saves to ~/.memoclaw/config.json)
memoclaw init

# Check free tier status
memoclaw status

# Print your wallet address
memoclaw whoami

# Store a memory
memoclaw store "User prefers dark mode" --importance 0.8 --tags preferences,ui --memory-type preference

# Store with additional flags
memoclaw store "Never deploy on Fridays" --importance 0.95 --immutable --pinned --memory-type correction
memoclaw store "Session note" --expires-at 2026-04-01T00:00:00Z --memory-type observation
memoclaw store --file ./notes.txt --importance 0.7 --tags meeting --memory-type general  # read content from file
memoclaw store "key fact" --id-only --memory-type general           # print only the UUID (for scripting)

# Batch store from stdin (one per line or JSON array)
echo -e "fact one\nfact two" | memoclaw store --batch --memory-type general
cat memories.json | memoclaw store --batch --memory-type general

# Recall memories
memoclaw recall "what theme does user prefer"
memoclaw recall "project decisions" --namespace myproject --limit 5
memoclaw recall "user settings" --tags preferences
# Note: To include linked memories, use `memoclaw relations list <id>` after recall.

# Get a single memory by ID
memoclaw get <uuid>

# List all memories
memoclaw list --namespace default --limit 20

# Update a memory in-place
memoclaw update <uuid> --content "Updated text" --importance 0.9 --pinned true
memoclaw update <uuid> --memory-type decision --namespace project-alpha
memoclaw update <uuid> --expires-at 2026-06-01T00:00:00Z

# Delete a memory
memoclaw delete <uuid>

# Pin / unpin a memory (shorthand for update --pinned true/false)
memoclaw pin <uuid>
memoclaw unpin <uuid>

# Lock / unlock a memory (shorthand for update --immutable true/false)
memoclaw lock <uuid>                           # immutable — cannot update or delete
memoclaw unlock <uuid>                         # make mutable again

# Edit a memory interactively in your editor
memoclaw edit <uuid>                           # uses $EDITOR, $VISUAL, or vi
memoclaw edit <uuid> --editor vim              # override editor

# Duplicate a memory
memoclaw copy <uuid>                           # new ID, mutable even if source was immutable
memoclaw copy <uuid> --namespace other-project --importance 0.9 --tags new-tag

# Move memories to another namespace
memoclaw move <uuid> --namespace archive
memoclaw move <uuid1> <uuid2> --namespace production
memoclaw move --from-namespace staging --namespace production          # move all from namespace
memoclaw move --tags stale --namespace archive                         # move by tag filter
memoclaw move --from-namespace old --since 30d --namespace recent      # move with date filter
memoclaw move --from-namespace staging --namespace prod --dry-run      # preview without moving
memoclaw move --from-namespace old --namespace archive --yes           # skip confirmation
memoclaw list --namespace staging --json | jq -r '.memories[].id' | memoclaw move --namespace production

# List all unique tags (free)
memoclaw tags
memoclaw tags --namespace project-alpha --json

# Watch for new memories in real-time
memoclaw watch                                 # stream to stdout
memoclaw watch --namespace myproject --interval 5
memoclaw watch --json | jq 'select(.importance > 0.8)'

# Ingest raw text (extract + dedup + relate)
memoclaw ingest --text "raw text to extract facts from"
memoclaw ingest --text "raw text" --auto-relate       # auto-link related facts
memoclaw ingest --file meeting-notes.txt              # read from file
echo "raw text" | memoclaw ingest                     # pipe via stdin

# Extract facts from text
memoclaw extract "User prefers dark mode. Timezone is PST."

# Consolidate similar memories
memoclaw consolidate --namespace default --dry-run

# Get proactive suggestions
memoclaw suggested --category stale --limit 10

# Migrate .md files to MemoClaw
memoclaw migrate ./memory/

# Bulk delete memories by ID
memoclaw bulk-delete uuid1 uuid2 uuid3

# Delete all memories in a namespace
memoclaw purge --namespace old-project
# ⚠️ Without --namespace, purge deletes ALL memories! Always scope it.
# memoclaw purge --force  ← DANGEROUS: wipes everything

# Manage relations
memoclaw relations list <memory-id>
memoclaw relations create <memory-id> <target-id> related_to
memoclaw relations delete <memory-id> <relation-id>

# Traverse the memory graph (related memories up to N hops)
memoclaw graph <memory-id>
memoclaw graph <memory-id> --depth 3                   # max hops (default: 2, max: 5)
memoclaw graph <memory-id> --limit 100                 # max memories returned (default: 50, max: 200)
memoclaw graph <memory-id> --depth 2 --relation-types supersedes,contradicts  # filter by relation type

# Assemble context block for LLM prompts
memoclaw context "user preferences and recent decisions" --limit 10
# Note: The API supports `summarize` and `include_metadata` params, but the CLI
# does not yet expose them as flags. Use the REST API directly if you need these.

# Full-text keyword search (free, no embeddings)
memoclaw search "PostgreSQL" --namespace project-alpha

# Core memories (free — highest importance, most accessed, pinned)
memoclaw core                              # dedicated core memories endpoint
memoclaw core --namespace project-alpha --limit 5
memoclaw core --raw | head -5              # content only, for piping
memoclaw list --sort-by importance --limit 10  # alternative via list

# Export memories
memoclaw export --format json --namespace default

# List namespaces with memory counts
memoclaw namespace list
memoclaw namespace stats           # detailed counts per namespace

# Usage statistics
memoclaw stats

# View memory change history
memoclaw history <uuid>

# Show content diff between memory versions (unified diff, free)
memoclaw diff <uuid>                   # latest vs previous
memoclaw diff <uuid> --revision 2      # specific revision
memoclaw diff <uuid> --all             # all diffs in sequence

# Quick memory count
memoclaw count
memoclaw count --namespace project-alpha

# Interactive memory browser (REPL) — search, view, update, delete, relate memories interactively
memoclaw browse
memoclaw browse --namespace project-alpha              # start in a specific namespace

# Import memories from JSON export
memoclaw import memories.json

# Show/validate config
memoclaw config show
memoclaw config check

# Check for CLI updates
memoclaw upgrade                       # check and prompt to install
memoclaw upgrade --check               # check only, don't install
memoclaw upgrade --yes                 # auto-install without prompting

# Aliases — human-readable shortcuts for memory IDs (local, free)
memoclaw alias set project-ctx <uuid>  # create alias
memoclaw alias list                    # list all aliases with previews
memoclaw alias rm project-ctx          # remove alias
# Use aliases anywhere a memory ID is expected:
memoclaw get @project-ctx
memoclaw update @project-ctx --content "updated"
memoclaw history @project-ctx
memoclaw diff @project-ctx

# Snapshots — point-in-time namespace backups (local, free to create)
memoclaw snapshot create               # snapshot default namespace
memoclaw snapshot create --name before-purge --namespace project1
memoclaw snapshot list                 # list all snapshots
memoclaw snapshot restore before-purge # restore (import cost applies)
memoclaw snapshot delete before-purge  # delete a snapshot

# Shell completions
memoclaw completions bash >> ~/.bashrc
memoclaw completions zsh >> ~/.zshrc

グローバルフラグ（すべてのコマンドで使用可能）：

-j, --json              # Machine-readable JSON output (best for agent piping)
-n, --namespace <name>  # Filter/set namespace
-l, --limit <n>         # Limit results
-o, --offset <n>        # Pagination offset
-t, --tags <a,b>        # Comma-separated tags
-f, --format <fmt>      # Output format: json, table, csv, yaml
-O, --output <file>     # Write output to file instead of stdout
-F, --field <name>      # Extract a specific field from output
-k, --columns <cols>    # Select columns: id,content,importance,tags,created
--raw                   # Content-only output (ideal for piping to other tools)
--wide                  # Wider columns in table output
-r, --reverse           # Reverse sort order
-m, --sort-by <field>   # Sort by: id, importance, created, updated
-w, --watch             # Continuous polling for changes
--watch-interval <ms>   # Polling interval for watch mode (default: 5000)
--agent-id <id>         # Agent identifier for multi-agent scoping
--session-id <id>       # Session identifier for per-conversation scoping
-s, --truncate <n>      # Truncate output to n characters
--no-truncate           # Disable truncation
-c, --concurrency <n>   # Parallel imports (default: 1)
-y, --yes               # Skip confirmation prompts (alias for --force)
--force                 # Skip confirmation prompts
-T, --timeout <sec>     # Request timeout (default: 30)
-M, --memory-type <t>   # Memory type (global alias for --memory-type)
--retries <n>           # Max retries on transient errors (default: 3)
--no-retry              # Disable retries (fail-fast mode)
--since <date>          # Filter by creation date (ISO 8601 or relative: 1h, 7d, 2w, 1mo, 1y)
--until <date>          # Filter by creation date (upper bound)
-p, --pretty            # Pretty-print JSON output
-q, --quiet             # Suppress non-essential output

エージェント向けのパターン：

memoclaw recall "query" --json | jq '.memories[0].content'   # parse with jq
memoclaw list --raw --limit 5                                 # pipe content only
memoclaw list --field importance --limit 1                    # extract single field
memoclaw export --output backup.json                          # save to file
memoclaw list --sort-by importance --reverse --limit 5        # lowest importance first
memoclaw list --since 7d                                      # memories from last 7 days
memoclaw list --since 2026-01-01 --until 2026-02-01          # date range filter
memoclaw recall "query" --since 1mo                          # recall only recent memories

セットアップ：

npm install -g memoclaw
memoclaw init              # Interactive setup — saves config to ~/.memoclaw/config.json
# OR manual:
export MEMOCLAW_PRIVATE_KEY=0xYourPrivateKey

環境変数：

• MEMOCLAW_PRIVATE_KEY — 認証に使用するウォレットの秘密鍵（必須。代わりに memoclaw init を使用することもできます）
• MEMOCLAW_URL — カスタム API エンドポイント（デフォルト：https://api.memoclaw.com）
• NO_COLOR — 色付き出力を無効化します（CI／ログで便利です）
• DEBUG — トラブルシューティング用のデバッグログを有効化します

無料枠： 最初の 100 回の呼び出しは無料です。CLI はウォレット署名認証を自動的に処理し、無料枠を使い切ると x402 決済に切り替えます。

---

仕組み

ウォレットアドレスがユーザー ID になります。アカウントも API キーも必要ありません。認証方法は 2 つあります。

1. 無料枠 — ウォレットでメッセージに署名します。100 回の呼び出しが可能で、支払いは不要です。
2. x402 決済 — 無料枠の終了後、各呼び出しに Base 上の USDC マイクロペイメントが含まれます。

どちらの方法も CLI が自動的に処理します。

料金

無料枠： ウォレットごとに 100 回の呼び出し（支払い不要）

無料枠終了後（Base 上の USDC）：

操作	料金
メモリを保存	$0.005
メモリを一括保存（最大 100 件）	$0.04
メモリを更新	$0.005
想起（セマンティック検索）	$0.005
一括更新	$0.005
ファクトを抽出	$0.01
統合	$0.01
取り込み	$0.01
コンテキスト	$0.01
移行（リクエストごと）	$0.01

料金ティア早見表

ティア	料金	コマンドと備考
無料	$0	list、get、delete、bulk delete、search（text）、core、suggested、relations、history、export、namespace list/stats、count、browse、config、tags、watch、alias、snapshot、pin/unpin、lock/unlock、edit、copy、move、whoami、status、upgrade（注3を参照）
埋め込み	1 回あたり $0.0051	store、store --file、store --batch2、update（コンテンツが変更された場合）、recall、batch update
ワークフロー	1 回あたり $0.01	context、extract、ingest、consolidate、migrate

1. 更新料金が発生するのは、保存されたコンテンツを変更した場合のみです（メタデータのみの編集は無料です）。recall と store の料金には、埋め込みの再生成が含まれます。
2. batch store は、最大 100 件のメモリーを対象とするリクエストごとに $0.04 かかり、同じ $0.005 の埋め込みティアが適用されます。
3. 無料の行には、最もよく使われるコマンドを記載しています。全リストについては、このファイルの上部付近にある「無料コマンド」セクションを参照してください。

無料： List、Get、Delete、Bulk Delete、Search（text）、Core、Suggested、Relations、History、Export、Import、Namespace、Stats、Count

セットアップ

上部の前提条件チェックリストと、memoclaw init の CLI 使用方法のセクションを参照してください。

ドキュメント： https://docs.memoclaw.com MCP サーバー： npm install -g memoclaw-mcp（MCP 対応クライアントからのツールベースのアクセス）

API リファレンス

HTTP エンドポイントの完全なドキュメントは api-reference.md にあります。 エージェントは、上記の CLI コマンドを優先して使用してください。API リファレンスは、HTTP を直接呼び出す場合にのみ参照してください。

---

保存するタイミング

• ユーザーの好みや設定
• 重要な決定とその根拠
• 今後のセッションで役立つ可能性のあるコンテキスト
• ユーザーに関する事実（名前、タイムゾーン、作業スタイル）
• プロジェクト固有の知識やアーキテクチャに関する決定
• エラーや修正から得た教訓

呼び出すタイミング

• ユーザーの好みについて推測する前
• ユーザーから「覚えていますか？」と聞かれたとき
• 新しいセッションを開始し、コンテキストが必要なとき
• 以前の会話のコンテキストが役立つとき
• 以前に尋ねた可能性のある質問を繰り返す前

ベストプラクティス

1. 具体的にする — 「Ana は vim バインディングを使う VSCode を好む」は「ユーザーはエディターが好き」よりも明確です
2. メタデータを追加する — タグを使うと、後から絞り込んで呼び出せます
3. 重要度を設定する — 重大な情報には 0.9 以上、あると便利な情報には 0.5 を設定します
4. memory_type を設定する — 減衰の半減期は memory_type によって異なります（correction：180d、preference：180d、decision：90d、project：30d、observation：14d、general：60d）
5. 名前空間を使う — プロジェクトまたはコンテキストごとにメモリーを分離します
6. 重複させない — 類似するコンテンツを保存する前に、呼び出してください
7. プライバシーを尊重する — パスワード、API キー、トークンは絶対に保存しないでください
8. 自然に減衰させる — 重要度が高く、最近の情報ほどランキングが上がります
9. 重要なメモリーをピン留めする — 減衰させたくない情報（例：ユーザーの名前）には pinned: true を使います
10. リレーションを使う — 関連するメモリーを supersedes、contradicts、supports でリンクすると、より豊かな呼び出しができます
11. 破壊的な操作の前にスナップショットを作成する — consolidate または purge の前に memoclaw snapshot create --name before-purge を実行します
12. エイリアスを使う — よく参照するメモリーには memoclaw alias set ctx <uuid> を使い、その後 memoclaw get @ctx で取得します

エラー処理

すべてのエラーは次の形式に従います：

{
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Missing payment header"
  }
}

エラーコード：

• UNAUTHORIZED (401) — ウォレット署名がないか、無効です
• PAYMENT_REQUIRED (402) — x402 決済がないか、無効です
• NOT_FOUND (404) — メモリーが見つかりません
• CONFLICT (409) — 変更不可のメモリーを変更しようとしました
• PAYLOAD_TOO_LARGE (413) — コンテンツが 8192 文字の上限を超えています
• VALIDATION_ERROR (422) — リクエスト本文が無効です
• RATE_LIMITED (429) — リクエストが多すぎます。時間をおいて再試行してください
• INTERNAL_ERROR (500) — サーバーエラー

---

エラーからの復旧

MemoClaw API の呼び出しに失敗した場合は、次の方法で対応してください。

API call failed?
├─ 401 UNAUTHORIZED → Wallet key missing or invalid. Run `memoclaw config check`.
├─ 402 PAYMENT_REQUIRED
│  ├─ Free tier? → Check MEMOCLAW_PRIVATE_KEY, run `memoclaw status`
│  └─ Paid tier? → Check USDC balance on Base
├─ 409 CONFLICT → Immutable memory — cannot update or delete. Store a new one instead.
├─ 413 PAYLOAD_TOO_LARGE → Content exceeds 8192 chars. Split into smaller memories.
├─ 422 VALIDATION_ERROR → Fix request body (check field constraints above)
├─ 404 NOT_FOUND → Memory was deleted or never existed
├─ 429 RATE_LIMITED → Back off 2-5 seconds, retry once
├─ 500/502/503 → Retry with exponential backoff (1s, 2s, 4s), max 3 retries
└─ Network error → Fall back to local files temporarily, retry next session

適切な縮退動作： MemoClaw に接続できない場合も、ユーザーを待たせないでください。一時的な保存にはローカルのスクラッチファイルを使い、API が利用可能になったら同期してください。メモリサービスの停止によって、ユーザーへの支援が妨げられないようにしてください。

---

ローカルファイルからの移行

ローカルの Markdown ファイル（例：MEMORY.md、memory/*.md）を永続化に使用している場合は、次の手順で移行できます。

ステップ 1：.md ファイルを移行する

専用の migrate コマンドを使用してください。このコマンドは ## ヘッダーでファイルを分割し、コンテンツハッシュで重複を排除し、重要度・タグ・memory_type を自動的に割り当て、1 バッチあたり最大 10 ファイルを処理します。

# Migrate a directory of .md files (recommended)
memoclaw migrate ./memory/

# Migrate a single file
memoclaw migrate ./MEMORY.md

会話の文字起こしやログなど、.md 形式ではない生テキストには、代わりに ingest を使用してください。

# Extract facts from raw text
cat transcript.txt | memoclaw ingest --namespace default

ステップ 2：移行を確認する

# Check what was stored
memoclaw list --limit 50
memoclaw count   # quick total

# Test recall
memoclaw recall "user preferences"

ステップ 3：重要なメモリをピン留めする

# Find your most important memories and pin them
memoclaw suggested --category hot --limit 20
# Then pin the essentials:
memoclaw update <id> --pinned true

ステップ 4：ローカルファイルをバックアップとして残す

ローカルファイルはすぐに削除しないでください。1 週間は両方のシステムを並行して使用し、想起の品質に問題がないことを確認してから、ローカルファイルを段階的に廃止してください。

---

マルチエージェントのパターン

複数のエージェントが同じウォレットを共有しながら、互いに分離する必要がある場合：

# Agent 1 stores in its own scope
memoclaw store "User prefers concise answers" \
  --importance 0.8 --memory-type preference --agent-id agent-main --session-id session-abc

# Agent 2 can query across all agents or filter
memoclaw recall "user communication style" --agent-id agent-main

エージェントごとの分離には agent_id を、会話ごとのスコープ設定には session_id を使用してください。名前空間はエージェントではなく、プロジェクトなどの論理ドメインに使用します。

---

トラブルシューティング

よくある問題とその解決方法：

Command not found: memoclaw
→ npm install -g memoclaw

"Missing wallet configuration" or auth errors
→ Run memoclaw init (interactive setup, saves to ~/.memoclaw/config.json)
→ Or set MEMOCLAW_PRIVATE_KEY environment variable

402 Payment Required but free tier should have calls left
→ memoclaw status — check free_calls_remaining
→ If 0: fund wallet with USDC on Base network

"ECONNREFUSED" or network errors
→ API might be down. Fall back to local files temporarily.
→ Check https://api.memoclaw.com/v1/free-tier/status with curl

`memoclaw recall` or `memoclaw search` immediately returns `Error: Internal server error`
→ Run `memoclaw list --limit 1` to confirm the API still responds (list is free / non-embedding).
→ If list works but every recall/search fails, the database migration `003_hybrid_retrieval.sql` (adds `memories.content_tsv`) hasn’t finished. Run the memocloud migrations against Neon (or your Postgres) and redeploy.
→ As of March 2026 the API auto-detects when `content_tsv` is missing and falls back to inline `to_tsvector('english', content)` so requests keep working, just slower. Make sure you’re on the latest API build to get that safety net.
→ While waiting on migrations, stick to `memoclaw list --limit 5 --sort-by importance` or jot critical facts in local scratch files so you can backfill once recall is healthy.

`memoclaw search "query"` returns `Error: Invalid memory ID format`
→ CLI ≤1.9.0 still points `memoclaw search` at `GET /v1/memories/search`, which the API interprets as `/v1/memories/:id` and rejects because "search" isn’t a UUID.
→ Run `memoclaw --version`. If it’s 1.9.0 or older, upgrade: `npm install -g anajuliabit/memoclaw-cli#fix/search-endpoint` (temporary) or, once published, `npm install -g memoclaw@latest` (≥1.9.1 uses `POST /v1/search`).
→ Need results immediately? Call the API directly: `curl -s https://api.memoclaw.com/v1/search -H "content-type: application/json" -d '{"query":"meeting notes","limit":5}' | jq`. This endpoint is FREE because it skips embeddings.
→ OpenClaw automations using the MemoClaw skill keep working because the skill already targets `POST /v1/search`. If your agent has to run locally, swap the failing CLI step for the skill’s `search` tool until you can upgrade the CLI.

Recall returns no results for something you stored
→ Check namespace — recall defaults to "default"
→ Try memoclaw search "keyword" for free text search
→ Lower min_similarity if results are borderline

Duplicate memories piling up
→ Always recall before storing to check for existing
→ Run memoclaw consolidate --namespace default --dry-run to preview merges
→ Then memoclaw consolidate --namespace default to merge

"Immutable memory cannot be updated"
→ Memory was stored with immutable: true — it cannot be changed or deleted by design

context --summarize or --include-metadata has no effect
→ The CLI does not yet support these flags (they are silently ignored).
→ The API supports `summarize` and `include_metadata` on POST /v1/context.
→ If you need these features, make a direct HTTP call instead of using the CLI.

recall --include-relations is not a valid flag
→ The CLI does not support --include-relations.
→ To get linked memories, first recall, then run `memoclaw relations list <id>` on results.

CLI --help shows wrong memory types (e.g. "core, episodic, semantic")
→ The CLI help text is outdated. The API accepts ONLY these types:
  correction, preference, decision, project, observation, general
→ Always use the types documented in this skill file, not the CLI --help output.

簡易ヘルスチェック

自動プリフライトスクリプトを実行すると、すべての項目を一度に確認できます。

bash scripts/preflight.sh   # checks CLI, config, API, free tier, memory count

または、手動で確認してください。

memoclaw config check    # Wallet configured?
memoclaw status          # Free tier remaining?
memoclaw count           # How many memories stored?
memoclaw stats           # Overall health