Prerequisites

• Docker Desktop 4.x+ with Docker Compose 2.24.4+
• Node 20+ (used at install AND runtime; no jq or other extras needed)
• bash 3.2+, plus standard POSIX utilities (awk, sed, grep, find, mktemp, tr, cut)
• git, curl

Cross-platform: macOS and Linux are first-class. Windows works via WSL2 or Git Bash: bootstrap is bash-only and intentionally avoids jq, realpath, gsed, or any other non-portable binary.

<details> <summary>Docker via Rancher Desktop / Colima (non-standard path)</summary>

If your docker comes from Rancher Desktop (~/.rd/bin/docker), Colima, or another non-standard location, the install scripts auto-resolve it: bootstrap.sh and scripts/lib.sh probe ~/.rd/bin, /usr/local/bin, /opt/homebrew/bin, and the Rancher app bundle before giving up, and you can force a specific binary with DOCKER_BIN=/path/to/docker. One caveat the scripts can't fix for you: the Claude Code / MCP-client process that spawns the memory server runs docker exec … from its own environment, and Rancher only adds ~/.rd/bin to your interactive shell PATH (via .zshrc/.bashrc). If the MCP server fails to start with "docker: command not found", ensure your client is launched from a shell that has ~/.rd/bin on PATH (or symlink docker into /usr/local/bin). </details>

<details> <summary>Windows-specific gotchas</summary>

- Line endings: the repo ships .gitattributes forcing LF on shell + Node + config files. If you cloned with core.autocrlf=true (Git for Windows default) BEFORE these directives existed locally, run git add --renormalize . && git checkout . to fix any CRLF in your working tree, otherwise bash will choke on #!/usr/bin/env bash\r. - Docker Desktop file sharing: under Docker Desktop → Settings → Resources, enable the drive (non-WSL) or the WSL2 distro that contains your project. Without this, the workspace bind mounts empty and scan_documents / absorb_files see no source files. - Symlinks: the repo ships zero symlinks; do not introduce any locally without enabling Windows Developer Mode (or accept that Git will substitute a 1-line text file for the symlink target). </details>

"Run dify-setup.sh" hint if any prereq is missing.

./.memory/src/scripts/mcp-smoke.sh

Install

The boilerplate is consumed as ./.memory/src/ inside your project, with its own git history retained for git pull updates. Two phases, drive each manually or via an AI prompt:

Why two prompts? The MCP server only becomes callable AFTER your client (Claude Desktop, Cursor, Codex) restarts to pick it up. Phase 2 uses MCP tools (list_datasets, create_dataset, absorb_files, ...) that don't exist before that restart, so it can't share a session with Phase 1. Run Phase 1, restart your client, then run Phase 2.

Manual install

```bash

🤖 AI-driven install

Phase 1 of 2. Host-side install only (clone, bootstrap, docker stack up). Run Phase 2 AFTER the stack is up AND your MCP client restarts.

Paste this prompt into your agent (Claude Code, Cursor, Codex) running inside the target project root:

Install the local Dify MCP memory boilerplate into this project. Target the current working directory unless I explicitly give you another path.

Steps:

1. Confirm the boilerplate Git URL with me first if you cannot infer it. Default: https://github.com/ctxr-dev/memory

2. Ask me for the project slug. Lowercase ASCII a-z, 0-9, hyphen (e.g. billing-api, docs-site). If I give you a name, propose a sanitised slug derived from the project folder name and confirm. The slug becomes the per-project Docker container, image, and Compose project name, so multiple projects can run their own memory stacks without collisions.

3. Ask me which LLM provider to use for the flush + compile pipeline:
   - claude (recommended; spawns `claude -p`, no API key needed)
   - codex (spawns `codex exec --json`, no API key needed)
   - anthropic (REST with ANTHROPIC_API_KEY in ./.memory/settings/.env)
   - openai (REST with OPENAI_API_KEY in ./.memory/settings/.env)
   Detect which CLIs are on PATH before asking. If only one is available, default to it and ask me to confirm.

4. Ask whether to install Claude Code hooks (default: yes). Hooks live in .claude/settings.json and wire SessionStart, PreCompact, PostCompact, SessionEnd, and PostToolUse (matcher ExitPlanMode, for auto-capturing approved plans into the `plans` slot) to ./.memory/src/scripts/hooks/. Other clients can adapt .agents/hooks.json manually.

5. Ask which MCP clients I want registered: Claude Desktop, Cursor, Codex/OpenAI, generic. Note the choices for step 8; the actual snippets only exist after bootstrap.sh runs.

6. Verify host prerequisites or tell me exactly what is missing:
   - docker (Docker Desktop or engine) with `docker compose` 2.24.4+
   - node 20+
   - git, curl, bash 3.2+
   bootstrap.sh itself only enforces docker + node + docker-compose-version; git and curl are needed by `git clone` and the Dify-version probe. No `jq`, `realpath`, or other extras are required (the install path is intentionally portable to Git Bash on Windows).

7. Run the install. If I chose Codex/OpenAI as a client in step 5 AND the `codex` CLI is on PATH, append `--register-codex` so bootstrap auto-runs `codex mcp add` for me; otherwise tell me to run that command manually after step 8:
   git clone <boilerplate-git-url> ./.memory/src
   ./.memory/src/bootstrap.sh --slug <slug> --llm-provider <provider> [--no-hooks if I declined] [--register-codex if Codex picked]

8. Static verification only (Docker not yet required; the stack is not up yet):
   bash -n ./.memory/src/bootstrap.sh ./.memory/src/scripts/*.sh ./.memory/src/scripts/hooks/*.sh
   node --check ./.memory/src/scripts/compile.mjs ./.memory/src/scripts/hooks/flush.mjs ./.memory/src/scripts/hooks/session-start.mjs
   node --check ./.memory/src/scripts/lib/*.mjs ./.memory/src/mcp-server/src/*.js
   ( cd ./.memory/src && npm test )

   Then print the requested client snippets from `./.memory/src/.agents/clients/` (now that bootstrap has rendered them):
   ./.memory/src/scripts/mcp-config.sh all
   For Codex (if not auto-registered in step 7):
   codex mcp add <slug>-memory -- docker exec -i <slug>-memory node src/index.js

9. Start the stack. WARN ME this is slow on first run: dify-bootstrap clones the upstream Dify repo (~hundreds of MB) and `up.sh` then pulls and builds Dify + the bridge image (2-5 minutes on a cold pull, multi-GB; ~30-60s once the Docker image cache is warm):
   ./.memory/src/scripts/up.sh
   (`up.sh` invokes `ui-url.sh` itself, so the Dify UI URL is printed when it finishes.)

10. Tell me the exact next steps after the stack is up:
    a) Open the printed Dify UI URL.
    b) Create the admin account, configure an embedding model under Settings -> Model Provider (REQUIRED before any high_quality dataset can be created).
    c) Open Knowledge -> Service API, create a Knowledge API key.
    d) Restart your MCP client (Claude Desktop / Cursor / Codex / your terminal-spawned agent) so it picks up the new memory MCP server. The server only becomes callable after this restart.
    e) Run `./.memory/src/scripts/dify-setup.sh` to wire datasets, install the per-document metadata schema, and (optionally) absorb my existing docs. ALTERNATIVELY paste the second AI prompt from the README (under "Onboarding -> AI-driven flow") to a fresh agent session for an MCP-driven walkthrough that uses list_datasets / create_dataset / scan_documents / absorb_files instead of the wizard.
    f) Final end-to-end smoke (only valid after step e): `./.memory/src/scripts/mcp-smoke.sh` — read-only round-trip across get_memory_config, search_memory (plain + filtered), and recall_lessons.

Stop and ask me whenever you would otherwise guess. Do not proceed past any step on assumption. Your config lives in `./.memory/settings/.env` (created from `.memory/src/.env.example`); the wizard (`dify-setup.sh`) manages it. If you must hand-edit, edit `./.memory/settings/.env` (there is no `.memory/src/.env`).

Atoms extracted by flush+compile

<details> <summary>Expand: atom types table</summary>

Seven atom types are produced by the flush LLM extractor (prompts/flush.md) and routed by compile. Each carries the metadata block (project_module, language, task_type, optional error_pattern) plus tags. The compile prompt biases toward update over create when atom_type, project_module, and (for lessons) error_pattern match: same fact never gets written twice; same lesson converges into one canonical document.

</details>

Tier 1 — Static. Requires: bootstrap.sh only. No Docker, no LLM.

bash -n ./.memory/src/bootstrap.sh ./.memory/src/scripts/.sh ./.memory/src/scripts/hooks/.sh node --check ./.memory/src/scripts/compile.mjs ./.memory/src/scripts/hooks/flush.mjs ./.memory/src/scripts/hooks/session-start.mjs node --check ./.memory/src/scripts/lib/.mjs ./.memory/src/mcp-server/src/.js

Tier 4 — End-to-end MCP smoke. Requires: up.sh + dify-setup.sh + DIFY_KNOWLEDGE_API_KEY + ≥1 dataset bound.

Verify the metadata schema is installed on the self_improvement slot.

docker exec -i "$(grep '^MCP_CONTAINER_NAME=' ./.memory/settings/.env | cut -d= -f2 | tr -d '\r')" \ node src/memory-cli.js list-metadata-fields --datasetId self_improvement

Client config

<details> <summary>Expand: client config</summary>

Generated client snippets live under .agents/clients/ after bootstrap:

./.memory/src/scripts/mcp-config.sh all              # print every client snippet
./.memory/src/scripts/mcp-config.sh codex            # | claude-desktop | cursor

For Codex/OpenAI:

codex mcp add <project-slug>-memory -- docker exec -i <project-slug>-memory node src/index.js

For Claude Desktop, Cursor, or generic MCP clients, merge .agents/mcp.json (or the matching .agents/clients/<client> snippet) into your client's MCP config. Do not paste API keys into client configs; they live only in ./.memory/settings/.env.

When --install-hooks is on (default), .claude/settings.json is rendered with the four lifecycle events wired to ./.memory/src/scripts/hooks/. Other clients can adapt .agents/hooks.json to their own hook format; see STACK.md for the event-to-script table.

</details>

Read-only by design: initialize, get_memory_config, plain + filtered search_memory,

Hook reference

<details> <summary>Expand: hook reference table</summary>

Hook timeouts: 130s for flush hooks (LLM defaults to 120s per call + headroom), 30s for PostToolUse/ExitPlanMode (no LLM, but multiple bridge round-trips: find + create + metadata + re-list + dedupe-delete), 15s for SessionStart (only emits a reminder + spawns compile detached).

</details>

Tier 6 — Direct CLI checks. Requires: bridge container running.

expect doc_metadata to include atom_type, tags, project_module,