# echo-fade-memory

Adopt this skill: https://proskills.md/skills/other/hiparker-echo-fade-memory-skill-echo-fade-memory

Page: https://proskills.md/skills/other/hiparker-echo-fade-memory-skill-echo-fade-memory
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skill/echo-fade-memory/SKILL.md
size: 6163
sha: 423a8424289c2a776ef293d3aeb4349f21be6394
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/SKILL.md

````text
---
name: echo-fade-memory
version: 1.3.0
description: "Runs a thin long-term memory workflow on top of the echo-fade-memory service. Use proactively whenever an answer may depend on prior session context, durable user facts, preferences, recent personal state, past decisions, corrections, unresolved work, or previously shared images/screenshots/files. Prefer low-cost recall before answering and store durable facts or visual artifacts early."
author: hiparker
keywords: [memory, ai-agent, long-term-memory, recall, store, forget, image-memory, multimodal, screenshot, ocr, dashboard, openclaw, cursor, codex, claude-code]
metadata:
  requires:
    runtime:
      - "echo-fade-memory server on http://127.0.0.1:8080 or EFM_BASE_URL"
      - "embedding backend: Ollama or OpenAI or Gemini"
---

# Echo Fade Memory

This skill turns `echo-fade-memory` into an installed **agent memory operating layer**.

The public agent contract is intentionally thin:

- `store`
- `recall`
- `forget`

Image memory is folded into the same `store/recall/forget` contract. Dashboard and debugging routes live under `/v1/dashboard/*` and are not part of the agent-facing tool surface.

## Natural Triggers in OpenClaw

Use this skill implicitly when the conversation includes:

- remember this / 记住这个
- what did we decide before / 上次定的是什么
- user preferences, durable constraints, corrections
- project decisions worth carrying across sessions
- screenshots, diagrams, receipts, whiteboards, or UI states that may matter later
- repeated failures that reveal a reusable workaround
- elliptical continuity prompts such as 那个、这个、继续刚才的、你知道的
- time-indexed prompts such as 今天、刚刚、最近、这次、又、还、还是、依然
- continuity checks such as 你记得吗、你不是知道吗、你忘了？

Prefer over-triggering low-cost recall to under-triggering and answering as if no history exists.

If `http://127.0.0.1:8080` is unreachable in a containerized environment, set:

```bash
export EFM_BASE_URL=http://host.docker.internal:8080
```

## Quick Reference

| Situation | Action |
|-----------|--------|
| Start of a task or session | Recall relevant context with `./scripts/recall.sh "<query>"` |
| User states a durable preference / decision / correction | Store it immediately with `./scripts/store.sh "<content>" --summary "<summary>" --type <type>` |
| User sends an image or screenshot worth keeping | Store it with `./scripts/store.sh "<file-path>" --object-type image` |
| Need old memory, image, or topic with one query | Use `./scripts/recall.sh "<query>"` |
| User asks to delete wrong or obsolete memory | Use `./scripts/forget.sh "<query-or-id>"` |
| Need debug analytics or dashboards | Open `/dashboard` or call `/v1/dashboard/*` |

## Core Workflow

### 1. Recall Before Responding

Before answering about prior decisions, preferences, goals, screenshots, or unresolved issues:

```bash
./scripts/recall.sh "database choice for this project"
```

Inspect:

- `mixed`
- `memories`
- `images`
- `entities`

If a recalled memory is fuzzy, you can still ground it with `GET /v1/memories/<id>/ground`, but keep that as an internal troubleshooting path rather than the default agent contract.

### 2. Store Durable Facts Early

When the user says something durable, store it before moving on.

Recommended minimal memory shape:

- `content`
- `summary`
- `type`

```bash
./scripts/store.sh \
  "User prefers dark mode and minimal UI" \
  --summary "dark mode preference" \
  --type preference
```

Advanced fields still exist, but only add them when you have a clear reason:

- `--importance`
- `--ref`
- `--kind`
- `--conflict-group`

Use higher `importance` only for:

- preferences
- corrections
- project decisions
- constraints
- explicit "remember this" statements

### 3. Store Images Through the Same Entry

When the conversation includes a screenshot, whiteboard, receipt, or other durable visual artifact.

Recommended minimal image shape:

- `file_path` or `url`
- optional `caption`
- optional `tags`
- optional `ocr_text`

```bash
./scripts/store.sh \
  "/absolute/path/to/meeting-whiteboard.png" \
  --object-type image \
  --caption "meeting whiteboard about rollout" \
  --tag rollout \
  --ocr-text "Deployment Checklist"
```

Advanced image flags still exist, but they are not the default mental model:

- `--session`
- `--kind`
- `--actor`
- `--memory-id`
- `--url`

Use image memory when the user is likely to ask:

- "上次那张图"
- "有猫那张图"
- "包含某句话的截图"
- "和那个决定相关的图片"

### 4. Forget Wrong or Obsolete State

If a memory or image is incorrect, unsafe, or obsolete:

```bash
./scripts/forget.sh "that obsolete deployment note"
./scripts/forget.sh "<image-id-or-query>" image
```

## Memory Taxonomy

| Situation | `memory_type` | Notes |
|-----------|---------------|-------|
| User preference | `preference` | Use high importance |
| Project decision | `project` | Add `conflict_group` for versioning |
| Goal / pending work | `goal` | Good for future follow-ups |
| Error workaround | `project` | Prefix summary with `error:` or `learning:` |
| Capability request | `goal` or `project` | Prefix summary with `feature-request:` |

## Scripts

| Script | Purpose |
|--------|---------|
| `scripts/health-check.sh` | Verify the server is reachable |
| `scripts/store.sh` | Unified store wrapper for memory and image objects |
| `scripts/recall.sh` | Unified federated recall wrapper |
| `scripts/forget.sh` | Unified forget wrapper for memory or image objects |
| `scripts/activator.sh` | Hook reminder for recall/store discipline |
| `scripts/error-detector.sh` | Hook reminder when command output looks like a failure |

## Setup

### Service Availability

```bash
./scripts/health-check.sh
```

### OpenClaw Config

Recommended entry in `openclaw.json`:

```json
{
  "skills": {
    "entries": {
      "echo-fade-memory": {
        "baseUrl": "http://host.docker.internal:8080"
      }
    }
  }
}
```

Recommended precedence:

1. `EFM_BASE_URL`
2. `skills.entries.echo-fade-memory.baseUrl`
3. default `http://127.0.0.1:8080`
````

## File: skill/echo-fade-memory/scripts/_resolve_base_url.py
size: 906
sha: 52e016bfa994161fcdf7c227bcd12389b9694ff3
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/scripts/_resolve_base_url.py

```text
#!/usr/bin/env python3
import json
import os
from pathlib import Path

# precedence:
# 1. EFM_BASE_URL
# 2. /Users/system/.openclaw/openclaw.json -> skills.entries.echo-fade-memory.baseUrl
# 3. /home/node/.openclaw/openclaw.json -> same path
# 4. default localhost

env = os.environ.get('EFM_BASE_URL')
if env:
    print(env)
    raise SystemExit(0)

candidates = [
    Path('/Users/system/.openclaw/openclaw.json'),
    Path('/home/node/.openclaw/openclaw.json'),
]

for path in candidates:
    if not path.exists():
        continue
    try:
        data = json.loads(path.read_text())
        value = (
            data.get('skills', {})
                .get('entries', {})
                .get('echo-fade-memory', {})
                .get('baseUrl')
        )
        if value:
            print(value)
            raise SystemExit(0)
    except Exception:
        pass

print('http://127.0.0.1:8080')
```

## File: skill/echo-fade-memory/scripts/activator.sh
size: 1058
sha: 55fef76b7ad7ccc1108980ebb7c241b4960302a8
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/scripts/activator.sh

```text
#!/bin/sh
set -eu

cat <<'EOF'
<echo-fade-memory-reminder>
Before answering, check whether durable memory should be part of the workflow:
- Recall relevant prior context first
- Prefer proactive recall for private-chat questions about user state, recent facts, previous decisions, or omitted context
- Over-trigger low-cost recall rather than answering as if no history exists
- Store new durable preferences, decisions, corrections, or lessons
- Reinforce memories that proved useful
- Ground fuzzy memories before trusting them

High-priority recall cues:
- 今天、刚刚、最近、这次、还是、又、依然
- 上次、之前、你还记得吗、你不是知道吗、你忘了？
- 那个、这个、继续刚才的、你知道的
- what the user is wearing, where they are, what they recently said or did

Useful commands:
- ./scripts/recall.sh "<query>"
- ./scripts/store.sh "<content>" --type preference|project|goal
- ./scripts/store.sh "/absolute/path/to/image.png" --object-type image --session "session:img"
</echo-fade-memory-reminder>
EOF
```

## File: skill/echo-fade-memory/scripts/error-detector.sh
size: 531
sha: a390fb0013696baca37d3868669fe521680e13a3
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/scripts/error-detector.sh

```text
#!/bin/sh
set -eu

OUTPUT="${CLAUDE_TOOL_OUTPUT:-}"

case "$OUTPUT" in
  *"error:"*|*"Error:"*|*"ERROR:"*|*"failed"*|*"fatal:"*|*"Traceback"*|*"Exception"*|*"Permission denied"*|*"command not found"*|*"No such file"*|*"non-zero"*)
    cat <<'EOF'
<echo-fade-memory-error-reminder>
A command error was detected.
If this failure revealed a reusable workaround, store it as durable memory:
- summarize the fix clearly
- use high importance
- mark it as project memory or goal memory
</echo-fade-memory-error-reminder>
EOF
    ;;
esac
```

## File: skill/echo-fade-memory/scripts/forget.sh
size: 938
sha: 4a023946cf96dda4dc5d5f96ee8c44a7d026a364
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/scripts/forget.sh

```text
#!/bin/sh
set -eu

SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
BASE_URL="${EFM_BASE_URL:-$($SCRIPT_DIR/_resolve_base_url.py)}"
TARGET="${1:-}"
OBJECT_TYPE="${2:-auto}"

if [ -z "$TARGET" ]; then
  echo "usage: $(basename "$0") <query-or-id> [memory|image|auto]" >&2
  exit 1
fi

python3 - "$BASE_URL" "$TARGET" "$OBJECT_TYPE" <<'PY'
import json
import sys
import urllib.request

base_url, target, object_type = sys.argv[1], sys.argv[2], sys.argv[3]
payload = {"query": target, "k": 5}
if object_type and object_type != "auto":
    payload["object_type"] = object_type
req = urllib.request.Request(
    f"{base_url.rstrip('/')}/v1/tools/forget",
    data=json.dumps(payload).encode("utf-8"),
    headers={"Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(req, timeout=15) as resp:
    data = json.loads(resp.read().decode("utf-8"))
print(json.dumps(data, indent=2, ensure_ascii=False))
PY
```

## File: skill/echo-fade-memory/scripts/health-check.sh
size: 179
sha: 6a58227ebccbe831c33fd714cee55b637345fb1d
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/scripts/health-check.sh

```text
#!/bin/sh
set -eu

SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
BASE_URL="${EFM_BASE_URL:-$($SCRIPT_DIR/_resolve_base_url.py)}"

curl -fsS "${BASE_URL%/}/v1/healthz"
```

## File: skill/echo-fade-memory/scripts/recall.sh
size: 782
sha: 4e78398e23af983747cb6785a7e554769b84091d
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/scripts/recall.sh

```text
#!/bin/sh
set -eu

SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
BASE_URL="${EFM_BASE_URL:-$($SCRIPT_DIR/_resolve_base_url.py)}"
QUERY="${1:-}"
K="${2:-5}"

if [ -z "$QUERY" ]; then
  echo "usage: $(basename "$0") <query> [k]" >&2
  exit 1
fi

python3 - "$BASE_URL" "$QUERY" "$K" <<'PY'
import json
import sys
import urllib.request

base_url, query, k = sys.argv[1], sys.argv[2], sys.argv[3]
req = urllib.request.Request(
    f"{base_url.rstrip('/')}/v1/tools/recall",
    data=json.dumps({"query": query, "k": int(k)}).encode("utf-8"),
    headers={"Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(req, timeout=15) as resp:
    data = json.loads(resp.read().decode("utf-8"))
print(json.dumps(data, indent=2, ensure_ascii=False))
PY
```

## File: skill/echo-fade-memory/scripts/store.sh
size: 2924
sha: dfaeb3ea41879f13c8efb92b4b126b95e1f481b6
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/scripts/store.sh

```text
#!/bin/sh
set -eu

SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
BASE_URL="${EFM_BASE_URL:-$($SCRIPT_DIR/_resolve_base_url.py)}"

python3 - "$BASE_URL" "$@" <<'PY'
import argparse
import json
import sys
import urllib.request

base_url = sys.argv[1]
argv = sys.argv[2:]

parser = argparse.ArgumentParser(
    prog="store.sh",
    description="Store a memory or image through the unified tool contract. Prefer minimal inputs: memory uses content+summary+type, image uses file_path/url plus optional caption/tags/ocr_text.",
)
parser.add_argument("payload", nargs="?")
parser.add_argument("--object-type", choices=["memory", "image"], default="memory")
parser.add_argument("--type", dest="memory_type", default="project")
parser.add_argument("--summary", default="")
parser.add_argument("--importance", type=float, default=0.8)
parser.add_argument("--ref", default="session:manual")
parser.add_argument("--kind", default="chat")
parser.add_argument("--conflict-group", default="")
parser.add_argument("--session", default="")
parser.add_argument("--actor", default="")
parser.add_argument("--url", default="")
parser.add_argument("--caption", default="")
parser.add_argument("--tag", action="append", dest="tags", default=[])
parser.add_argument("--ocr-text", default="")
parser.add_argument("--memory-id", action="append", dest="memory_ids", default=[])
args = parser.parse_args(argv)

payload = {"object_type": args.object_type}
if args.object_type == "memory":
    if not args.payload:
        raise SystemExit("usage: store.sh <content> [--summary TEXT] [--type TYPE]")
    payload.update(
        {
            "content": args.payload,
            "memory_type": args.memory_type,
            "summary": args.summary,
            "importance": float(args.importance),
            "source_kind": args.kind,
            "source_ref": args.ref,
        }
    )
    if args.conflict_group:
        payload["conflict_group"] = args.conflict_group
else:
    if not args.payload and not args.url:
        raise SystemExit("usage: store.sh <file-path> --object-type image [--caption TEXT] [--tag TAG] [--ocr-text TEXT] or store.sh --object-type image --url URL")
    payload.update(
        {
            "file_path": args.payload or "",
            "url": args.url,
            "source_session": args.session,
            "source_kind": args.kind,
            "source_actor": args.actor,
            "caption": args.caption,
            "tags": args.tags,
            "ocr_text": args.ocr_text,
            "linked_memory_ids": args.memory_ids,
        }
    )

req = urllib.request.Request(
    f"{base_url.rstrip('/')}/v1/tools/store",
    data=json.dumps(payload).encode("utf-8"),
    headers={"Content-Type": "application/json"},
    method="POST",
)
with urllib.request.urlopen(req, timeout=15) as resp:
    data = json.loads(resp.read().decode("utf-8"))
print(json.dumps(data, indent=2, ensure_ascii=False))
PY
```

## File: skill/echo-fade-memory/references/examples.md
size: 1581
sha: de47e0b69e3a4b5da47d4cb8e6f353c17d994c1e
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/references/examples.md

````text
# Examples

Concrete usage patterns for running agent memory on top of `echo-fade-memory`.

Assumption in this file:

- commands are run from the installed skill directory
- script paths use `./scripts/...`

## 1. Store a Preference

```bash
./scripts/store.sh \
  "User prefers concise answers and dislikes nested bullets" \
  --summary "response style preference" \
  --type preference
```

## 2. Store a Project Decision

```bash
./scripts/store.sh \
  "Project decision: use chromem-go as the embedded vector store to keep setup lightweight and dependency-free" \
  --summary "vector backend decision" \
  --type project
```

If the decision really needs stronger durability or versioning, then add advanced flags such as `--importance` or `--conflict-group`.

## 3. Store a Screenshot

```bash
./scripts/store.sh \
  "/absolute/path/to/deployment-checklist.png" \
  --object-type image \
  --caption "deployment checklist screenshot" \
  --tag deployment \
  --ocr-text "Deployment Checklist"
```

## 4. Recall Before Answering

```bash
./scripts/recall.sh "vector backend decision"
./scripts/recall.sh "the screenshot containing Deployment Checklist"
```

Typical response fields to inspect:

- `mixed`
- `memories`
- `images`
- `entities`

## 5. Forget Incorrect or Obsolete State

```bash
./scripts/forget.sh "temporary deployment note"
./scripts/forget.sh "latency spike screenshot" image
```

## 6. Ground a Fuzzy Memory

```bash
curl -sS "$EFM_BASE_URL/v1/memories/<id>/ground"
```

Use this when a memory is old, fragmentary, or needs source verification before reuse.
````

## File: skill/echo-fade-memory/references/hooks-setup.md
size: 4115
sha: 6cab737f9c0cec082285866d61fa11184b5496cc
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/references/hooks-setup.md

````text
# Hook Setup

Use these hooks when you want the agent to behave more like the reference skills:

- recall/store discipline before and during tasks
- reminder to persist errors and learnings

The scripts are intentionally lightweight and only emit reminder text.

Assumption in this file:

- the skill is used in its installed form
- commands inside the skill use `./scripts/...`
- external hook configs should prefer explicit installed paths such as `~/.openclaw/skills/echo-fade-memory/scripts/...`

## Environment

All scripts honor:

```bash
export EFM_BASE_URL=http://127.0.0.1:8080
```

If unset, they default to `http://127.0.0.1:8080`.

## Claude Code Setup

Create `.claude/settings.json`:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.openclaw/skills/echo-fade-memory/scripts/activator.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.openclaw/skills/echo-fade-memory/scripts/error-detector.sh"
          }
        ]
      }
    ]
  }
}
```

## Codex Setup

Create `.codex/settings.json`:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.openclaw/skills/echo-fade-memory/scripts/activator.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.openclaw/skills/echo-fade-memory/scripts/error-detector.sh"
          }
        ]
      }
    ]
  }
}
```

## Minimal Setup

If you want lower prompt overhead, install only the activator:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.openclaw/skills/echo-fade-memory/scripts/activator.sh"
          }
        ]
      }
    ]
  }
}
```

## What the Scripts Do

| Script | Trigger | Behavior |
|--------|---------|----------|
| `activator.sh` | `UserPromptSubmit` | Reminds the agent to recall relevant memory first, then store durable new facts |
| `error-detector.sh` | `PostToolUse` for Bash | Detects likely command failures and reminds the agent to capture the workaround as memory |

## Installed OpenClaw / Shared Skill Paths

Recommended explicit installed-path setup:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.openclaw/skills/echo-fade-memory/scripts/activator.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.openclaw/skills/echo-fade-memory/scripts/error-detector.sh"
          }
        ]
      }
    ]
  }
}
```

## Verification

### Test health

```bash
./scripts/health-check.sh
```

### Test activator output

```bash
./scripts/activator.sh
```

Expected: an XML-style reminder block mentioning recall, store, reinforce, and ground.

### Test error detector output

```bash
CLAUDE_TOOL_OUTPUT="fatal: example failure" ./scripts/error-detector.sh
```

Expected: a reminder block suggesting error-memory capture.

## Troubleshooting

### Script not found

Use absolute paths if your agent runs from a different working directory:

```json
{
  "command": "/absolute/path/to/echo-fade-memory/scripts/activator.sh"
}
```

### Permission denied

```bash
chmod +x ~/.openclaw/skills/echo-fade-memory/scripts/*.sh
```

### Too much prompt overhead

- Use only `activator.sh`
- Add a matcher like `memory|decision|preference|fix|error`
- Keep the script output short

## Security Notes

- These hook scripts only emit text
- They do not write files or mutate the service
- The error detector reads `CLAUDE_TOOL_OUTPUT` and pattern-matches common failures
````

## File: skill/echo-fade-memory/references/openclaw-integration.md
size: 2818
sha: 19db0c2a9774039bd39aa009194ab77b7d9bc5ee
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/references/openclaw-integration.md

````text
# OpenClaw Integration

This package supports OpenClaw in the same spirit as the reference skills, but the durable memory backend is `echo-fade-memory`.

## Goal

Use OpenClaw workspace context plus `echo-fade-memory` for:

- persistent recall across sessions
- decision / preference capture
- reminders to store learnings and errors as memories

## Install the Skill Source

From a source checkout, copy this skill into your OpenClaw skills directory:

```bash
cp -r ./skill/echo-fade-memory ~/.openclaw/skills/echo-fade-memory
```

## Install the Hook Source

From a source checkout, copy the OpenClaw hook:

```bash
cp -r ./skill/echo-fade-memory/hooks/openclaw ~/.openclaw/hooks/echo-fade-memory
```

Enable it:

```bash
openclaw hooks enable echo-fade-memory
```

## What the Hook Injects

On `agent:bootstrap`, the hook injects a short reminder telling the agent to:

1. recall before answering
2. store durable preferences / decisions / corrections
3. reinforce reused memories
4. ground fuzzy memories before trusting them

## Runtime Assumption

The hook defaults to:

```bash
http://127.0.0.1:8080
```

In containerized OpenClaw environments, this may be unreachable. In that case, use:

```bash
export EFM_BASE_URL=http://host.docker.internal:8080
```

You can adapt the reminder or your environment to a different URL via `EFM_BASE_URL`.

## Suggested OpenClaw Workflow

### On session start

- Read your usual workspace files
- Recall relevant project memory with a focused query
- Ground anything that looks uncertain

### During work

- Store user preferences immediately
- Store project decisions immediately
- Store debugging lessons that may recur

### During errors

- Treat important failures as memory-worthy if they reveal a project-specific workaround
- Prefer storing a concise fix rather than the full raw log

## Recommended Memory Shapes

| OpenClaw event | Store as |
|----------------|----------|
| User preference | `memory_type=preference`, `importance>=0.9` |
| Project decision | `memory_type=project`, optional `conflict_group` |
| Missing capability | `memory_type=goal`, summary starts with `feature-request:` |
| Debugging lesson | `memory_type=project`, summary starts with `error:` or `learning:` |

## Example

```text
User: "We switched to chromem because we wanted the embedded vector store to stay lightweight and easy to run."

Agent (internal):
1. Store project decision memory
2. Continue task

Later:
User: "Why did we switch to chromem?"

Agent (internal):
1. Recall memory
2. Ground if needed
3. Answer
4. Reinforce the memory
```

## Verification

Check the hook is installed:

```bash
openclaw hooks list
```

Check the skill is visible:

```bash
openclaw status
```

Check the memory service:

```bash
~/.openclaw/skills/echo-fade-memory/scripts/health-check.sh
```
````

## File: skill/echo-fade-memory/references/openclaw-natural-trigger.md
size: 1807
sha: 18033e0b2b2e35ea6c97b4e68cd5554c170afa14
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/references/openclaw-natural-trigger.md

````text
# OpenClaw 自然触发接入建议

目标：让 agent 在不需要用户显式说“调用 echo-fade-memory”的情况下，自然使用这套长期记忆。

## 触发条件

出现以下语义时，应优先进入 echo-fade-memory 流程：

- 记忆类指令：记住这个、你记一下、以后按这个来、先别忘了
- 跨会话回忆：上次我们说过什么、之前定的是啥、你还记得吗、我不是说过吗
- 稳定信息写入：用户偏好、长期约束、项目决策、用户纠正、可复用 workaround、feature request
- 视觉记忆：截图、白板、票据、流程图、UI 状态
- 复用记忆回答：需要先回忆上下文再回答的问题

## OpenClaw 内部行为建议

### 回答前

如果问题明显依赖过去信息，先 recall：

```bash
export EFM_BASE_URL=http://host.docker.internal:8080
./skills/echo-fade-memory/scripts/recall.sh "<query>"
```

### 新信息出现时

立即 store，不要等会话结束：

```bash
export EFM_BASE_URL=http://host.docker.internal:8080
./skills/echo-fade-memory/scripts/store.sh \
  "用户偏好极简回答" \
  --summary "偏好：简洁直接" \
  --type preference
```

### 用户发来截图时

```bash
export EFM_BASE_URL=http://host.docker.internal:8080
./skills/echo-fade-memory/scripts/store.sh \
  "/absolute/path/to/screenshot.png" \
  --object-type image \
  --caption "关键截图" \
  --tag screenshot
```

### 用户要求删除时

```bash
export EFM_BASE_URL=http://host.docker.internal:8080
./skills/echo-fade-memory/scripts/forget.sh "那条旧的部署说明"
```

## 推荐的 memory_type 映射

| 场景 | memory_type |
|------|-------------|
| 用户偏好 | preference |
| 项目决定 | project |
| 纠正/经验/报错 workaround | project |
| 未来想做的能力 | goal |
````

## File: skill/echo-fade-memory/assets/memory-templates.md
size: 2272
sha: 1793d1863cc367fb7155f1517a78d7bd386fc6a7
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/assets/memory-templates.md

````text
# Memory Templates

These payload templates turn the reference skills' common workflows into `echo-fade-memory` requests.

## Preference Template

```json
{
  "content": "User prefers dark mode and concise answers.",
  "summary": "preference: dark mode and concise answers",
  "memory_type": "preference",
  "importance": 0.95,
  "source_refs": [
    {
      "kind": "chat",
      "ref": "session:2026-03-18"
    }
  ]
}
```

## Decision Template

```json
{
  "content": "Project decision: use chromem-go as the embedded vector store to keep setup lightweight and dependency-free.",
  "summary": "decision: use chromem-go for embedded vectors",
  "memory_type": "project",
  "importance": 0.9,
  "conflict_group": "project:vector-backend",
  "source_refs": [
    {
      "kind": "chat",
      "ref": "session:architecture"
    }
  ]
}
```

## Error / Learning Template

```json
{
  "content": "Learning: use /usr/bin/git instead of legacy /usr/local/bin/git when commit tooling requires --trailer support.",
  "summary": "error: use system git for trailer support",
  "memory_type": "project",
  "importance": 0.88,
  "source_refs": [
    {
      "kind": "chat",
      "ref": "session:git-workaround"
    }
  ]
}
```

## Feature Request Template

```json
{
  "content": "Feature request: expose emotional_weight in POST /v1/memories for emotionally salient facts.",
  "summary": "feature-request: emotional weight api",
  "memory_type": "goal",
  "importance": 0.7,
  "source_refs": [
    {
      "kind": "chat",
      "ref": "session:feature-request"
    }
  ]
}
```

## Session Handoff Template

```json
{
  "content": "Current state: Docker compose now uses chromem by default and restart policy unless-stopped. Next step is validating live recall workflows.",
  "summary": "session handoff: docker + chromem status",
  "memory_type": "working",
  "importance": 0.75,
  "source_refs": [
    {
      "kind": "chat",
      "ref": "session:handoff"
    }
  ]
}
```

## Prompt Pattern

When converting a reference-skill style learning into memory:

1. Put the full lesson in `content`
2. Make `summary` short and searchable
3. Use `importance` instead of `emotional_weight` for now
4. Always include `source_refs`
5. Use `conflict_group` when the fact may evolve over time
````

## File: skill/echo-fade-memory/.clawhub/origin.json
size: 148
sha: d6b4c1ef29561f3451418625e2cc11df379e9410
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/.clawhub/origin.json

```text
{
  "version": 1,
  "registry": "https://clawhub.ai",
  "slug": "echo-fade-memory",
  "installedVersion": "1.0.0",
  "installedAt": 1773899705634
}
```

## File: skill/echo-fade-memory/_meta.json
size: 135
sha: 76a9fd20a33670a087bb860b2e9b7a655d8faa90
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/_meta.json

```text
{
  "ownerId": "kn7c6kvd5n68d5jxatjwrpfe2d82fx1b",
  "slug": "echo-fade-memory",
  "version": "1.0.0",
  "publishedAt": 1773884250699
}
```

## File: skill/echo-fade-memory/bootstrap/EFM_OPENCLAW.md
size: 980
sha: 908289916555ff422aed19578ca22790e1e1c05c
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/bootstrap/EFM_OPENCLAW.md

````text
# Echo Fade Memory for OpenClaw

当任务涉及以下内容时，优先使用 echo-fade-memory：

- 跨会话记忆
- 用户偏好、约束、决定
- 用户纠正、错误复盘、可复用经验
- 截图、白板、票据等视觉记忆
- 需要先回忆再回答的问题

服务地址：

- 默认 `http://127.0.0.1:8080`
- 当前环境若在容器内，可设置 `EFM_BASE_URL=http://host.docker.internal:8080`

建议流程：

1. 回答前先 recall
2. 新的 durable 信息立即 store
3. 用户要求删除时用 forget
4. 记忆模糊时再走 ground

常用命令：

```bash
export EFM_BASE_URL=http://host.docker.internal:8080
./skills/echo-fade-memory/scripts/recall.sh "<query>"
./skills/echo-fade-memory/scripts/store.sh "<content>" --type preference|project|goal
./skills/echo-fade-memory/scripts/store.sh "/absolute/path/to/image.png" --object-type image --session "session:img"
./skills/echo-fade-memory/scripts/forget.sh "那条不该保留的旧记忆"
```
````

## File: skill/echo-fade-memory/hooks/openclaw/handler.js
size: 1446
sha: 7b7c3a1b2152373727ee812b35f6e3fe17c01f57
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/hooks/openclaw/handler.js

```text
/**
 * Echo Fade Memory hook for OpenClaw.
 *
 * Injects a bootstrap reminder so the agent uses the local memory service
 * as an active part of its workflow.
 */

const REMINDER_CONTENT = `
## Echo Fade Memory Reminder

Use echo-fade-memory as a natural long-term memory layer in OpenClaw.

Prefer this workflow when:
- the user says "记住这个" / "remember this"
- the user asks about something said before
- a durable preference, constraint, decision, correction, or workaround appears
- the answer clearly depends on prior session context

Before answering:
- Recall relevant project memory first
- Ground memories if they look fuzzy or uncertain

During work:
- Store durable user preferences, decisions, and corrections
- Reinforce memories that proved useful
- Forget memories when the user explicitly asks

If 127.0.0.1:8080 is unreachable, try:
- export EFM_BASE_URL=http://host.docker.internal:8080
`.trim();

const handler = async (event) => {
  if (!event || typeof event !== "object") {
    return;
  }

  if (event.type !== "agent" || event.action !== "bootstrap") {
    return;
  }

  if (!event.context || typeof event.context !== "object") {
    return;
  }

  if (Array.isArray(event.context.bootstrapFiles)) {
    event.context.bootstrapFiles.push({
      path: "ECHO_FADE_MEMORY_REMINDER.md",
      content: REMINDER_CONTENT,
      virtual: true,
    });
  }
};

module.exports = handler;
module.exports.default = handler;
```

## File: skill/echo-fade-memory/hooks/openclaw/HOOK.md
size: 510
sha: 2a7c4069a1c00bf5b14d4bc960f7d6660fd8ea03
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/skill/echo-fade-memory/hooks/openclaw/HOOK.md

````text
---
name: echo-fade-memory
description: "Injects a bootstrap reminder to recall and persist durable memory using the echo-fade-memory service."
metadata: {"openclaw":{"emoji":"🧠","events":["agent:bootstrap"]}}
---

# Echo Fade Memory Hook

Injects a short bootstrap reminder so the agent remembers to:

- recall before answering
- store durable preferences and decisions
- reinforce reused memories
- ground fuzzy memories before trusting them

## Enable

```bash
openclaw hooks enable echo-fade-memory
```
````

## File: README.md
upstream: https://github.com/hiparker/echo-fade-memory/blob/main/README.md

````text
# Echo Fade Memory

An **AI memory middleware** built for forgetting. It helps agents remember, decay, recall, ground, and eventually forget information in a controlled, explainable way.

**定位**：面向 AI Agent 的可衰减记忆中间件。它不是完整 Agent 框架，也不是会话上下文替代品，而是基础设施层的记忆生命周期引擎。详见 [docs/CORE.md](docs/CORE.md)。

---

## Documentation

| Language | Plan / 规划 |
| -------- | ----------- |
| [English](docs/PLAN.en.md) | Architecture, roadmap, tech stack |
| [中文](docs/PLAN.zh.md) | 架构设计、实现路径、技术选型 |

---

## Overview

- **Forgetting as a feature**: this is not just a memory store, but a memory lifecycle engine.
- **Explainable recall**: recall returns `score`, `strength`, `freshness`, `fuzziness`, `decay_stage`, `source_refs`, `why_recalled`, and `needs_grounding`.
- **Multi-form memory**: one memory can carry raw content, summary, embedding, residual content, lifecycle state, and source references.
- **Pluggable runtime**: use it from CLI, HTTP API, and later MCP / SDK integrations.

---

## 概述

- **遗忘即特性**：不是单纯"存得更多"，而是让记忆按生命周期演化。
- **可解释召回**：召回结果不仅有内容，还会返回 `score`、`strength`、`freshness`、`why_recalled`、`needs_grounding` 等字段。
- **多形态记忆**：同一条记忆可同时拥有原文、摘要、embedding、残留内容、来源引用和生命周期状态。
- **基础设施层定位**：上层 `SKILL` 或 agent framework 负责策略编排，本项目负责底层记忆执行。

---

## Dashboard Snapshot

`/dashboard` 现在提供一个面向 Phase 2 的轻量观察与操作面板：

- `Overview`: 全局 KPI、健康状态、memory/image/entity 对齐情况
- `Detail`: Top-N、趋势、分布、覆盖率等分析视图
- `Workbench`: 一个统一输入框联动 memory、image、entity 的 federated recall

### Overview

![Overview](images/overview.png)

### Detail

![Detail](images/detail.png)

### Workbench

![Workbench](images/workbench.png)

Integrity check mode defaults to lightweight:

- compare SQL total vs vector total when backend supports count;
- run sampled ID checks (default `sample_size=200`) when backend supports ID existence checks.

---

## Quick Start

**Prerequisites**: [Go 1.26+](https://go.dev/dl/), [Ollama](https://ollama.ai/) with `nomic-embed-text` model.

Canonical Go module path: `github.com/hiparker/echo-fade-memory`.

The default vector backend is `local`, so a plain `make build` / `make test` flow stays dependency-light.
By default, runtime assets now live under `~/.echo-fade-memory`, with data isolated per workspace.

```bash
# Pull embedding model
ollama pull nomic-embed-text

# Build
make build

# Remember a memory
./echo-fade-memory remember "Project meeting: decided to use Go and Bleve for Phase 1"

# Recall with explainable fields
./echo-fade-memory recall "meeting decision"

# Reinforce a memory after reuse
./echo-fade-memory reinforce <memory_id>

# Ground a fuzzy memory back to its sources
./echo-fade-memory ground <memory_id>

# HTTP API
./echo-fade-memory serve
# HTTP API (custom runtime home for local debugging)
./echo-fade-memory serve --workdir /Users/system/.echo-fade-memory --workspace debug-local
# HTTP API (custom runtime + port)
./echo-fade-memory serve --workdir /Users/system/.echo-fade-memory --workspace debug-local --port 9090
# POST   /v1/memories {"content":"...", "memory_type":"project", "source_refs":[...]}
# GET    /v1/memories?q=query
# POST   /v1/memories/<id>/reinforce
# GET    /v1/memories/<id>/ground
# POST   /v1/memories/explain {"query":"..."}
# POST   /v1/memories/decay
# POST   /v1/tools/store {"content":"..."} or {"object_type":"image","file_path":"..."}
# POST   /v1/tools/recall {"query":"...","k":5}
# POST   /v1/tools/forget {"query":"...","object_type":"memory|image"} or {"id":"..."}
# GET    /v1/dashboard/stats/overview?window_days=30
# GET    /v1/dashboard/stats/integrity?sample_size=200
# GET    /v1/dashboard/stats/detail?window_days=30&top_k=10&sample_size=200
# POST   /v1/dashboard/workbench/query {"query":"...","k":5}
# Dashboard: GET /dashboard
```

**Docker**:

```bash
# 方式一：先启动外部 Ollama 容器，再启动 echo-fade-memory
# 默认 chromem（纯 Go 嵌入式向量库）
./scripts/start-ollama-embedding.sh
docker compose up --build

# 方式二：含 Ollama，自动拉取 nomic-embed-text
docker compose -f docker-compose.ollama.yml up --build
```

---

## Configuration

Copy `config.example.json` to `config.json` and customize:

| Section | Key | Description |
|---------|-----|-------------|
| embedding | type, url, model, dimensions, api_key, base_url | `type`: ollama, openai, gemini; `url` for ollama; `api_key` for openai/gemini |
| decay | tau, alpha, epsilon | strength = 1/(1+(t/τ)^α) × reinforce; tau=halflife, alpha=shape |
| vector_store | type, path, milvus_host, milvus_port, milvus_db | `local`, `chromem` (Docker default), `milvus` |
| storage | type, path | `sqlite` (default), `postgres`, `mysql` |

Env vars: `EMBEDDING_TYPE`, `EMBEDDING_URL`, `EMBEDDING_MODEL`, `EMBEDDING_API_KEY`, `ECHO_FADE_MEMORY_HOME`, `ECHO_FADE_MEMORY_WORKSPACE`, etc.

**OpenAI**: `"embedding": {"type": "openai", "model": "text-embedding-3-small", "api_key": "sk-..."}` (or `OPENAI_API_KEY`)

**Gemini**: `"embedding": {"type": "gemini", "model": "text-embedding-004", "api_key": "..."}` (or `GOOGLE_API_KEY`)

**Priority**: Default < config.json < Env

### Runtime Layout

By default the project uses a global runtime home:

```text
~/.echo-fade-memory/
  workspaces/<workspace-id>/
    data/
      memories.db             # SQLite metadata
      vector/
        local/vectors.json    # local vector backend
        chromem/              # chromem-go persistent data
      bleve/                  # full-text index
```

- `ECHO_FADE_MEMORY_HOME` overrides the global runtime root.
- `ECHO_FADE_MEMORY_WORKSPACE` overrides the derived workspace id.
- `DATA_PATH` still wins if you want a fully custom data directory.
- Docker compose files bind-mount `${HOME}/.echo-fade-memory` to `/root/.echo-fade-memory` and set a stable `ECHO_FADE_MEMORY_WORKSPACE`.

`serve` also supports runtime overrides via CLI flags (equivalent to env vars):

```bash
./echo-fade-memory serve --workdir /Users/system/.echo-fade-memory
./echo-fade-memory serve --workdir /Users/system/.echo-fade-memory --workspace debug-local
./echo-fade-memory serve --workdir /Users/system/.echo-fade-memory --workspace debug-local --port 9090
./echo-fade-memory serve --help
```

### Vector Backends

- `local`: pure Go, stores vectors in `vectors.json`; default for `make build` / `make test`.
- `chromem`: pure Go embedded vector database ([chromem-go](https://github.com/philippgille/chromem-go)); default for Docker. Persistent, no external service needed.
- `milvus`: external service backend for larger or remote deployments.

Invalid `vector_store.type` values fail fast at startup.

---

## Memory Shape

Each memory can include:

- `content`: original text
- `summary`: a compact recall-oriented representation
- `memory_type`: `long_term`, `working`, `preference`, `project`, `goal`
- `lifecycle_state`: `fresh`, `reinforced`, `weakening`, `blurred`, `archived`, `forgotten`
- `source_refs`: provenance pointers such as chat/file/github/url
- `residual_form` and `residual_content`: the current faded view
- `conflict_group` and `version`: lightweight versioning scaffold for same-topic memories

## API Snapshot

Agent-facing HTTP routes are now intentionally thin:

- `POST /v1/tools/store`
- `POST /v1/tools/recall`
- `POST /v1/tools/forget`

Core memory and debug HTTP routes remain available:

- `POST /v1/memories`
- `GET /v1/memories?q=...`
- `POST /v1/memories/explain`
- `POST /v1/memories/decay`
- `GET /v1/memories/:id`
- `DELETE /v1/memories/:id`
- `POST /v1/memories/:id/reinforce`
- `GET /v1/memories/:id/ground`
- `GET /v1/memories/:id/reconstruct`
- `GET /v1/memories/:id/versions`
- `GET /v1/healthz`
- `GET /v1/readyz`
- `GET /v1/dashboard/stats/overview?window_days=30`
- `GET /v1/dashboard/stats/integrity?sample_size=200`
- `GET /v1/dashboard/stats/detail?window_days=30&top_k=10&sample_size=200`
- `POST /v1/dashboard/workbench/query`

````
