memclaw

Memclaw — Workspace Manager

The agent's external brain for projects. Once activated, the agent continuously syncs artifacts and knowledge into the corresponding LiveDoc, so that anyone (including future sessions or teammates) can load that workspace and instantly recover full context.

Core Concepts

Concept	Description
Workspace	One project = one LiveDoc
Active Workspace	Current session state; all operations auto-sync to this workspace
README	The agent's memory of the project; actively maintained by the agent
Artifacts	Important outputs; the agent asks before saving
Registry	~/.memclaw/workspaces.json, mapping project names to LiveDoc IDs and project summaries

Registry format:

{
  "workspaces": {
    "Health Management": {
      "id": "nkYv32xA2dEHNpyT4xdZkq",
      "summary": "Triggers when user talks about diet, exercise, weight, calories, health tracking"
    }
  }
}

Registry maintenance rules:

• After creating a workspace → add a record with id and summary
• After loading a workspace → if it is not already in the registry, add it
• After deleting a workspace → remove the corresponding record
• After renaming → update the record name
• The summary field syncs from the README summary field. If the API returns a summary, use it; otherwise generate a one-line project description in the user's language.
• The registry key must be the project name (in the user's language). Never use a short_id as the key.
• If the API errors (502/401/timeout), do not write or modify the registry. Do not use placeholders or short_id as a fallback. Wait until the API is healthy again before writing.

Project existence verification (important):

• Never decide that a project exists based on memory alone. Before saying "this project already exists", you must verify it via the registry file or $SCRIPT list --keyword.
• short_id must come from a real query result in the current turn (registry, list, or create output), not from stale context in your head.
• If project verification fails (API error), do not pretend the project exists and do not invent project metadata. Tell the user there is a network issue and retry later, or create a new project directly.

Script Shorthand

In all commands below, $SCRIPT means:

node memclaw/scripts/run.mjs

Path resolution: this script path is relative to the installed skill directory. If memclaw/scripts/run.mjs cannot be found, try absolute paths:

1. node ~/.openclaw/skills/memclaw/scripts/run.mjs
2. node ~/.claude/skills/memclaw/memclaw/scripts/run.mjs

The script automatically loads ~/.memclaw/env for the API key. No manual source is required.

Commands Reference

Command	Description
create	Create a new LiveDoc (required: --name)
list	List all LiveDocs
update <short_id>	Update a LiveDoc
delete <short_id>	Delete a LiveDoc
resources <short_id>	List resources in a LiveDoc
resource <short_id> <resource_id>	Get details for a single resource
add-doc <short_id>	Create a text document resource (required: --content)
add-urls <short_id>	Add URL resources (required: --urls, comma-separated, max 10)
upload <short_id>	Upload a file resource (required: --file, optional: --convert)
remove-resource <short_id> <resource_id>	Delete a resource
update-resource <short_id> <resource_id>	Update resource title, snippet, or thumbnail
update-resource-content <short_id> <resource_id>	Update Markdown content of an ai_doc resource (required: --content)
retrieve <short_id>	Semantic search (required: --query, optional: --resource-ids)
route <short_id>	Route relevant resources by query (required: --query)
content <short_id> <resource_id>	Get text content of a resource (cached locally)
download <short_id> <resource_id>	Download the source file to local disk
ppt-retrieve <short_id>	PPT page deep retrieval (required: --resource-id, --page-number, --query)
get-readme <short_id>	Get README (returns summary + content)
update-readme <short_id>	Create or replace README (required: --content or --summary, at least one)
append-readme <short_id>	Append content to README (required: --content)
delete-readme <short_id>	Delete README

When NOT to Use This Skill

• Simple casual chat or clarification questions
• One-off generation tasks unrelated to any project/workspace
• When the user has not installed the Memclaw NPM package yet

---

Workflows

0. First Install

User pastes the GitHub install link → run installation → after completion, automatically enter login flow (0a).

0a. Login / Re-authorization

Trigger conditions (any one is enough):

• First installation, Key not yet configured
• Any API call returns: {"status":401,"code":"UNAUTHORIZED","message":"Invalid API Key"}

Flow:

1. Send the login link:

   "Please click this link to log in / register a Felo account: https://felo.ai/settings/api-keys After that, paste the Key here and I will finish the setup for you automatically."

2. User pastes Key → write configuration:

   export FELO_API_KEY="<user's key>"
   

   Or persist it into ~/.memclaw/env (depending on platform).
3. Verify by running $SCRIPT list
   • Success + first install → show the first-use introduction below
   • Success + re-auth → confirm authorization updated, then retry the failed command
   • Failure → tell the user the key is invalid and ask them to paste again

First-use introduction (show only on first install, not on re-authorization):

After showing the intro below, you must also write a reminder into MEMORY.md so the agent remembers MemClaw in future conversations:

## MemClaw Skill

I have the MemClaw external-brain skill installed. When the user talks about a topic that may relate to an existing project, the plugin auto-injects the project list. I must load the corresponding project before answering. Never rely on my own memory for project-related questions.

Present a first-use introduction to the user (in the user's language) covering these points:

• They can create a new project (a dedicated workspace)
• They can load an existing project to restore context
• They can list projects or browse what's inside
• Important outputs can be saved into the project
• All work records are automatically synced; they can view them anytime at https://memclaw.me/

1. Load Workspace

1. Read ~/.memclaw/workspaces.json and fuzzy-match by project name. If not found locally, immediately try $SCRIPT list --keyword.
2. Found: set it as the current active workspace (also record the LiveDoc object's is_shared property) → run $SCRIPT get-readme SHORT_ID → present the README as the project briefing to the user → append the link https://felo.ai/livedoc/SHORT_ID?from=claw. If the README is empty or missing, fall back to $SCRIPT resources SHORT_ID and show the resource list. If is_shared is true, add a reminder: "(read-only — shared project)".
   • README is an index, not the full dataset. After loading, only read the README. Do not proactively fetch document contents.
   • When you need specific data, inspect the "Document Directory" section in the README, find the matching Resource ID, then fetch it on demand via $SCRIPT content SHORT_ID RESOURCE_ID.
3. Multiple matches: do not guess. Ask the user directly: "Should this go into ‘X’ or ‘Y’?”
4. Not found: reply "No workspace named '[X]' was found. Want me to create one?"

2. Create Workspace

There are two paths:

Path A — user explicitly asks to create one:

1. Infer from conversation context what this project is for and how it can help the user.
2. Confirm using a "value proposition" style. Never ask open-ended questions:
   • Good: "I’ll create a ‘Health Management’ project for you. From now on, whenever you tell me what you ate, I’ll automatically calculate calories and track progress. Sound good?"
   • Good: "I’ll create an ‘Investments’ project for you. From now on, all analyses and insights we discuss will be saved automatically. Sound good?"
   • Bad: "What is the goal of this project?" ← absolutely do not ask this. Most users will get stuck.
3. User confirms → create the workspace → initialize the README with the inferred goals → set it as the active workspace

   $SCRIPT create --name "<project name>" --description "<workspace description>"
   

4. Confirm creation with the workspace link: https://felo.ai/livedoc/SHORT_ID?from=claw
5. If the user's need involves ongoing data recording (diet, exercise, investment tracking, client follow-ups, etc.), you must also do the following during creation:
   • Infer the data fields from the user's needs, then use add-doc to create a data document (content = Markdown table header)
   • In the README's Write Rules section, specify which data types write into which document (including Resource ID)
   • In the README's Document Directory, record the document name, purpose, and Resource ID
6. If the need does not involve ongoing structured recording, the rules and document directory can be refined gradually as the user actually uses the project.

Path B — the agent notices a repeatedly recurring topic: When the user repeatedly talks about the same topic across multiple conversations but there is still no corresponding workspace:

1. Proactively ask: "You often talk about [X]. Want me to create a project to keep track of it?"
2. User agrees → create the workspace → initialize the README from current context (record goals and any user preferences already expressed)
3. If the conversation already produced data, save it as the first document using add-doc
4. Confirm creation with the workspace link, mentioning that the previous content has been saved: https://felo.ai/livedoc/SHORT_ID?from=claw

When creating a project, never interrogate the user with a long setup questionnaire. Goals, rules, and preferences should emerge naturally as the project is used.

3. Document Management

The README contains the Document Directory (see Section 4). That directory is the single source of truth telling you what documents exist and what they are for. Whenever you are about to write data, always look there first.

Decision flow before writing data:

1. If the user explicitly specifies a target document → operate on that document directly; write rules do not override explicit user intent.
2. If the README contains Write Rules → follow the Write Rules and write into the document specified there.
3. If there are no Write Rules, read the Document Directory in the README:
   • If a suitable existing document can hold the new data → use update-resource-content to append the data
   • If not → use add-doc to create a new document, then update the README's Document Directory
4. If the user explicitly asks for a new document → create a new one even if an old one could have been reused.

Important: same-type data should use a single document. Do not split it by date or by number of writes. Only split if the user explicitly asks for it.

Common write commands:

Action	Command
Create new document	$SCRIPT add-doc SHORT_ID --title "<title>" --content "<content>"
Append to existing document	$SCRIPT update-resource-content SHORT_ID RESOURCE_ID --content "<full updated text>"
Add web links	$SCRIPT add-urls SHORT_ID --urls "<urls>"
Upload local file	$SCRIPT upload SHORT_ID --file /path/to/file --convert

Note: update-resource-content is a full overwrite operation, so you must first read the existing content via $SCRIPT content SHORT_ID RESOURCE_ID, merge in the new data, then overwrite the full updated text.

About saving artifacts (ask before saving):

If ACTIVE_WORKSPACE.is_shared (shared read-only) is true, skip this entirely — do not ask, and do not try to save.

After producing an important long-form result (for example a detailed research report, data analysis, or long copywriting draft), ask the user once: "Do you want me to save this into the project?" Only ask for important final outputs. Do not ask for intermediate drafts or short casual replies.

4. README Maintenance

If ACTIVE_WORKSPACE.is_shared is true, skip this entire section — do not read or write the README.

The README is the agent's core memory of the project. It has two jobs: telling the agent what the project is for, and telling it where to find the data. The agent maintains this proactively; you do not need user permission.

README has two API fields:

• summary: a one-line project description (max 2000 chars). The plugin syncs this into the registry for fuzzy topic matching.
• content: the full README body (Markdown).

README structure — it must contain the following sections (use the user's language for section headers and content):

# [Project Name]

## Goal
[Project background, core objectives, user's personal preferences]

## Rules
[How the agent should work in this project, how to handle user data]

## Write Rules
[Specify which data types go into which document. User's explicit instructions override these rules]
- [Data type A] → write to "Document Name" (Resource ID: xxx)
- [Data type B] → write to "Document Name" (Resource ID: xxx)
- Data not covered by write rules → ask user whether to create a new document
- When changing data structure or storage strategy, always update write rules and document directory in sync

## Document Directory
| Document | Purpose | Resource ID |
|----------|---------|-------------|
| Diet Log | Daily meals and calories | res_abc123 |
| Gold Analysis | Gold market analysis and insights | res_def456 |

The Document Directory is critical. Every time the agent needs to read or write data, it should consult this table first. Resource ID lets the agent use $SCRIPT content SHORT_ID RESOURCE_ID directly without doing extra list lookups.

README should NOT contain:

• endlessly growing raw logs of daily data (daily meal logs, investment details, meeting minutes, etc.)
• text that grows forever with every conversation
• these all belong in separate documents (see Section 3)

Example — README for a health-management project (illustrative structure only; generate content in the user's language):

# Health Management

## Goal
User wants to improve fatty liver through healthy weight loss, maintaining a 500-1000kcal calorie deficit daily.
User casually mentions what they ate, I estimate calories and record. Doesn't like using apps, finds them tedious. Weekly summary of performance.

## Rules
- User sends meal data → I estimate calories → silently append to diet log document
- User sends exercise data → record exercise data → append to the same diet log document
- User asks "how was this week" → I read the diet log → summarize and conclude
- Write method: first use content to read existing document → append new row to table → use update-resource-content to overwrite full text

## Write Rules
- Diet data (what was eaten, calories) → write to "Diet Log" (Resource ID: res_abc123)
- Exercise data (exercise calories, stairs climbed, etc.) → write to "Diet Log" (Resource ID: res_abc123)
- User's questions and analysis requests → do not write to any document, answer directly
- User expresses new preferences or rule changes → update README
- Forbidden to create a second data document, all records write only to the above document

## Document Directory
| Document | Purpose | Resource ID |
|----------|---------|-------------|
| Diet Log | Daily meals, exercise, and calorie deficit | res_abc123 |

When you MUST update the README:

• Right after the project is created — record the core goal you just inferred
• When the user expresses new preferences or workflow requirements — add them into Goal or Rules
• Whenever you create a new standalone document — add its name, purpose, and Resource ID into the Document Directory, and update the Write Rules
• When the user asks to change the data structure or storage strategy — update both Write Rules and Document Directory
• When the project's big direction changes — rewrite Goal

When you should NOT update the README:

• When you are only appending new data into an existing document
• When you are simply repeating a routine operation that the project already follows

Update method: read first → merge the change into the correct section → overwrite the full README. Never blindly append to the end.

1. Run $SCRIPT get-readme SHORT_ID to read the current state
2. Merge the change into the correct section (Goal / Rules / Write Rules / Document Directory)
3. Add Last updated: YYYY-MM-DD
4. Use $SCRIPT update-readme SHORT_ID --summary "<one-line description>" --content "<full updated content>" to overwrite the full updated content

Initialize from scratch (when the README is completely empty): Use update-readme together with --summary to write the full skeleton in one go. Fill Goal with the information you currently have; Rules and Document Directory can start empty.

5. Query Workspace Knowledge

Use resources + content to directly fetch project knowledge and source material. content caches extracted content internally under ~/.memclaw/cache/{livedocid}/{resource_id}_{ts}.md. It still returns the full extracted text content directly, so you do not need to manage the cache yourself.

$SCRIPT resources SHORT_ID
$SCRIPT content SHORT_ID RESOURCE_ID

Read the full content returned, extract what matters, and answer the user naturally. Never dump robotic lists of what you found.

6. Refresh Workspace

When the user says "refresh this" or you suspect the workspace may have been changed externally by someone else, re-fetch everything below:

$SCRIPT get-readme SHORT_ID
$SCRIPT resources SHORT_ID

Update your internal understanding of the project state. Then tell the user: "Workspace refreshed." If something actually changed, summarize the important differences briefly (for example, a new file appeared).

7. List Contents

Use $SCRIPT resources SHORT_ID to show the resources in the workspace, grouped by type. Newer artifacts should appear first.

---

Session State

ACTIVE_WORKSPACE = { name: "project-x", short_id: "abc123", is_shared: false }

• This state is set when the user loads or creates a project, and should only be cleared when the user explicitly asks to close the project.
• If there is no active state but the user tries to save / record / query data, you must ask: "There is no active project right now — which project do you want to operate on?"
• The is_shared flag comes from the LiveDoc object returned by list or create. If is_shared = true, the project is read-only: skip all write operations (including create/update docs, upload, update README). Read operations are still allowed. If the user insists on writing, reply: "This project is shared read-only. I can view it, but I cannot modify it."

Error Handling

Error	What to do
Key missing / API returns 401 UNAUTHORIZED	Trigger the login flow (see Section 0a).
LiveDoc ID is invalid / cannot be found	Suggest reconnecting it or creating a new one.
Local registry not found	Proactively create an empty ~/.memclaw/workspaces.json file: { "workspaces": {} }.
Multiple fuzzy matches and not sure which one	Show all candidates and ask the user to pick.

User Notification Rules

Keep notifications short and standardized. One line is enough — no long operational reports.

What happened	Required notification
Loaded workspace	Confirm loaded, include project name + link https://felo.ai/livedoc/SHORT_ID?from=claw
Created workspace	Confirm created, include project name + link
Switched workspace	Confirm switched, include project name + link
Wrote into a document or created a new document	Confirm recorded, include link
Saved an important artifact after asking	Confirm saved with document title + link
Proactively updated the README	Confirm project memory updated + link
Just queried data / chatted	Do not say you queried documents — just give the answer directly

Do not stack multiple operational messages like a menu. If you both wrote a document and updated the README directory, merge them into one short confirmation with the link.

Integration with Other Felo APIs

Besides core workspace management, you can also call Felo's advanced APIs at any time to generate content for the current project. Three critical preconditions:

1. Authentication: FELO_API_KEY is already available in the environment. Always send the header: Authorization: Bearer $FELO_API_KEY
2. Context binding: whenever a Felo endpoint supports livedoc_short_id, you must pass the current ACTIVE_WORKSPACE.short_id. This makes the generated result automatically land inside the current project's LiveDoc.
3. Self-service API lookup: if you need other advanced capabilities (deep web research, X/Twitter scraping, YouTube subtitle extraction, etc.) and you do not know the exact endpoint, look it up yourself in the official API docs instead of asking the user: https://openapi.felo.ai/docs/

Special Case: PPT Task API

PPT generation is a special async polling flow. Follow it carefully to avoid hanging:

1. Pick a theme: optionally query themes first via GET /v2/ppt-themes
2. Create task: POST /v2/ppts (required: query and livedoc_short_id), then record the returned task ID
3. Poll silently: every 10 seconds call GET /v2/tasks/{task_id}/historical. When a success status appears, extract ppt_url from the response and deliver it to the user.

---

Final Reminders (Important Rules)

• Always respond in the user's language
• Always use the LiveDoc short_id consistently in operations
• Execute commands immediately — do not narrate before acting
• Updating the README directory is the agent's job — do it proactively, do not wait for the user to push you
• Every time you save or modify files, include the workspace link in the reply
• Always respond in the user's language — if user speaks Chinese reply in Chinese, if user speaks English reply in English