feat(setup): add Alma target

CHANGELOG.md

@@ -13,6 +13,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   consolidation, evidence retrieval, and operational metrics, logs and traces.
   Existing Memory commands and databases retain the public CLI behavior.
   The separate hosted frontend and UI/UX are not part of this source snapshot.
+- `mnemon setup --target alma` installs a skill, a `mem` shim, and one
+  `app.ready` hook into `~/.config/alma/`. Alma does not inject hook stdout into
+  the model context, so the integration does not use the lifecycle-hook shape:
+  the hook only refreshes a marker-delimited block inside `MEMORY.md`, which
+  Alma already injects into its system prompt each request, and recall stays a
+  decision the host model makes through the skill. The block is rewritten only
+  when its content changes, so an unchanged start does not invalidate Alma's
+  prompt prefix. `mnemon setup --eject --target alma` removes the block, the
+  skill, the shim, and the hook, keeping any backups left in the bridge
+  directory.
 - `npm install --global @mnemon-dev/mnemon` is now the canonical CLI install
   path. Tagged releases publish pinned native artifacts for macOS, Linux, and
   Windows before advancing the npm `latest` or `next` channel.

README.md

@@ -303,6 +303,26 @@ One command deploys the mnemon skill, prompt files, and Hermes shell hooks to
 `on_session_finalize`. Hermes may prompt once to approve the installed shell
 hooks.
 
+### [Alma](https://alma.now)
+
+```bash
+mnemon setup --target alma --yes
+```
+
+One command deploys the mnemon skill, a `mem` shim, and a single `app.ready`
+hook to `~/.config/alma/`. Alma's hook stdout is not injected into the model
+context — only `decision`, `reason`, and `updatedInput` from the last JSON line
+are consumed — so the integration is deliberately shaped differently from the
+lifecycle-hook targets: the hook does one job (refresh a generated block inside
+`MEMORY.md`, which Alma already injects into its system prompt every request),
+and recall is left to the model through the skill. The block is delimited by
+`<!-- mnemon:begin -->` / `<!-- mnemon:end -->` and everything outside those
+markers is preserved byte for byte, because Alma's own prompt tells the model to
+write to the same file.
+
+Alma has no project-local hook configuration, so this target is user-global
+only.
+
 ### [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
 
 DeepSeek Harness (DSH) integrates through the [dsh-mnemon](https://github.com/omdsh-dev/dsh-mnemon) plugin, which layers DSH's runtime memory, managed project documents, and Mnemon's long-term memory spaces into one supervised three-tier memory system.
@@ -401,7 +421,7 @@ memory is useful.
 
 - **Zero user-side operation** — install once; supported runtimes can use hooks, minimal runtimes can use persistent rules
 - **LLM-supervised** — the host LLM decides what to remember, update, and forget; no embedded LLM, no API keys
-- **Multi-framework support** — Claude Code, Codex, Cursor, ZCode, TRAE/TRAE Work, Qoder/QoderWork, CodeBuddy, WorkBuddy, Kimi Code, OpenCode, and Hermes Agent (hooks/plugins), OpenClaw (plugins), Pi (extensions), MiniMax Code and Nanobot (skills), DeepSeek Harness (via the dsh-mnemon plugin), and more
+- **Multi-framework support** — Claude Code, Codex, Cursor, ZCode, TRAE/TRAE Work, Qoder/QoderWork, CodeBuddy, WorkBuddy, Kimi Code, OpenCode, and Hermes Agent (hooks/plugins), OpenClaw (plugins), Pi (extensions), Alma (skill + `app.ready` hook), MiniMax Code and Nanobot (skills), DeepSeek Harness (via the dsh-mnemon plugin), and more
 - **Runtime-native integration** — runtime-specific `SKILL.md`, shared `guide.md`, and supported hooks or extensions
 - **Four-graph architecture** — temporal, entity, causal, and semantic edges, not just vector similarity
 - **Intent-native protocol** — three primitives (`remember`, `link`, `recall`) map to the LLM's cognitive vocabulary, not database syntax; structured JSON output with signal transparency

cmd/memory/setup.go

@@ -2,6 +2,7 @@ package memory
 
 import (
 	"fmt"
+	"os/exec"
 	"runtime"
 	"strings"
 
@@ -25,9 +26,9 @@ var setupCmd = &cobra.Command{
 
 By default, installs to project-local config (.claude/, .codex/, .cursor/, .zcode/, .minimax/, .trae/, .qoder/, .codebuddy/, .workbuddy/, .opencode/, .openclaw/, .nanobot/, .pi/).
 Use --global to install to user-wide config (~/.claude/, ~/.codex/, ~/.cursor/, ~/.zcode/, ~/.minimax/, ~/.trae/, ~/.qoder/, ~/.codebuddy/, ~/.workbuddy/, ~/.config/opencode/, ~/.openclaw/, ~/.nanobot/workspace/, ~/.pi/agent/).
-Hermes Agent, QoderWork, and Kimi Code use native user config at ~/.hermes/, ~/.qoderwork/, and ~/.kimi-code/.
+Hermes Agent, QoderWork, Kimi Code, and Alma use native user config at ~/.hermes/, ~/.qoderwork/, ~/.kimi-code/, and ~/.config/alma/.
 
-Supported environments: Claude Code, Codex, Cursor, ZCode, MiniMax Code, Trae, Qoder, QoderWork, CodeBuddy, WorkBuddy, Kimi Code, OpenCode, OpenClaw, Nanobot, Pi, Hermes Agent.
+Supported environments: Claude Code, Codex, Cursor, ZCode, MiniMax Code, Trae, Qoder, QoderWork, CodeBuddy, WorkBuddy, Kimi Code, OpenCode, OpenClaw, Nanobot, Pi, Hermes Agent, Alma.
 
 Examples:
   mnemon setup                              # Interactive: project-local install
@@ -44,23 +45,24 @@ Examples:
   mnemon setup --target kimi                # Non-interactive: Kimi Code skill and hooks
   mnemon setup --target opencode            # Non-interactive: OpenCode skill and plugin
   mnemon setup --target hermes              # Non-interactive: Hermes Agent only
+  mnemon setup --target alma                # Non-interactive: Alma skill and hook
   mnemon setup --eject                      # Interactive: remove integrations
   mnemon setup --eject --target claude-code # Non-interactive: remove Claude Code only
   mnemon setup --yes                        # Auto-confirm all prompts`,
 	RunE: runSetup,
 }
 
 func init() {
-	setupCmd.Flags().StringVar(&setupTarget, "target", "", "target environment (claude-code, codex, cursor, zcode, minimax-code, trae, qoder, qoderwork, codebuddy, workbuddy, kimi, opencode, openclaw, nanobot, pi, hermes)")
+	setupCmd.Flags().StringVar(&setupTarget, "target", "", "target environment (claude-code, codex, cursor, zcode, minimax-code, trae, qoder, qoderwork, codebuddy, workbuddy, kimi, opencode, openclaw, nanobot, pi, hermes, alma)")
 	setupCmd.Flags().BoolVar(&setupEject, "eject", false, "remove mnemon integrations")
 	setupCmd.Flags().BoolVar(&setupYes, "yes", false, "auto-confirm all prompts (CI-friendly)")
 	setupCmd.Flags().BoolVar(&setupGlobal, "global", false, "install to user-wide config instead of project-local config")
 	rootCmd.AddCommand(setupCmd)
 }
 
 func runSetup(cmd *cobra.Command, args []string) error {
-	if setupTarget != "" && setupTarget != "claude-code" && setupTarget != "codex" && setupTarget != "cursor" && setupTarget != "zcode" && setupTarget != "minimax-code" && setupTarget != "trae" && setupTarget != "qoder" && setupTarget != "qoderwork" && setupTarget != "codebuddy" && setupTarget != "workbuddy" && setupTarget != "kimi" && setupTarget != "opencode" && setupTarget != "openclaw" && setupTarget != "nanobot" && setupTarget != "pi" && setupTarget != "hermes" {
-		return fmt.Errorf("invalid target %q (must be claude-code, codex, cursor, zcode, minimax-code, trae, qoder, qoderwork, codebuddy, workbuddy, kimi, opencode, openclaw, nanobot, pi, or hermes)", setupTarget)
+	if setupTarget != "" && setupTarget != "claude-code" && setupTarget != "codex" && setupTarget != "cursor" && setupTarget != "zcode" && setupTarget != "minimax-code" && setupTarget != "trae" && setupTarget != "qoder" && setupTarget != "qoderwork" && setupTarget != "codebuddy" && setupTarget != "workbuddy" && setupTarget != "kimi" && setupTarget != "opencode" && setupTarget != "openclaw" && setupTarget != "nanobot" && setupTarget != "pi" && setupTarget != "hermes" && setupTarget != "alma" {
+		return fmt.Errorf("invalid target %q (must be claude-code, codex, cursor, zcode, minimax-code, trae, qoder, qoderwork, codebuddy, workbuddy, kimi, opencode, openclaw, nanobot, pi, hermes, or alma)", setupTarget)
 	}
 
 	envs := setup.DetectEnvironments(setupGlobal)
@@ -168,6 +170,13 @@ func installEnv(env *setup.Environment) error {
 		err = installPi(env)
 	case "hermes":
 		err = installHermes(env)
+	case "alma":
+		// Alma's install seeds the MEMORY.md block, which needs a store to read
+		// from. Ensure it exists first, then install.
+		if err = initDefaultStore(); err != nil {
+			return err
+		}
+		return installAlma(env)
 	}
 	if err != nil {
 		return err
@@ -1493,6 +1502,67 @@ func selectHermesOptionalHooks() setup.HookSelection {
 	return sel
 }
 
+// ─── Alma ───────────────────────────────────────────────────────────
+
+func installAlma(env *setup.Environment) error {
+	configDir := env.ConfigDir
+
+	fmt.Printf("\nSetting up Alma (%s)...\n", configDir)
+
+	fmt.Println("\n[1/4] Skill")
+	if path, err := setup.AlmaWriteSkill(configDir); err != nil {
+		setup.StatusError(0, 0, "Skill", err)
+		return err
+	} else {
+		setup.StatusOK(0, 0, "Skill", path)
+	}
+
+	fmt.Println("\n[2/4] Shim")
+	shimPath, err := setup.AlmaWriteShim(configDir)
+	if err != nil {
+		setup.StatusError(0, 0, "Shim", err)
+		return err
+	}
+	setup.StatusOK(0, 0, "Shim: mem", shimPath)
+
+	fmt.Println("\n[3/4] Hook")
+	if path, err := setup.AlmaWriteHook(configDir, "prime.sh", assets.AlmaPrimeHook); err != nil {
+		setup.StatusError(0, 0, "Hook: prime", err)
+		return err
+	} else {
+		setup.StatusOK(0, 0, "Hook: prime", path)
+	}
+
+	fmt.Println("\n[4/4] Config")
+	if path, err := setup.AlmaRegisterHooks(configDir, setup.HookSelection{}); err != nil {
+		setup.StatusError(0, 0, "Hooks config", err)
+		return err
+	} else {
+		setup.StatusUpdated(0, 0, "Hooks config", path)
+	}
+
+	// Seed the block now so a fresh install shows memory on the very first
+	// turn instead of waiting for the next app start. Best effort: the hook
+	// does the same thing and a failure here must not fail the install.
+	if out, syncErr := exec.Command(shimPath, "sync").CombinedOutput(); syncErr != nil {
+		fmt.Printf("  note      hot index not seeded yet (%v); the app.ready hook will retry\n", syncErr)
+		_ = out
+	}
+
+	fmt.Println()
+	fmt.Println("Setup complete!")
+	fmt.Printf("  Skill     %s/skills/mnemon/SKILL.md\n", configDir)
+	fmt.Printf("  Shim      %s/mnemon-bridge/mem\n", configDir)
+	fmt.Printf("  Hook      %s/mnemon-bridge/prime.sh (app.ready)\n", configDir)
+	fmt.Printf("  Hot index %s/MEMORY.md (mnemon block)\n", configDir)
+	fmt.Println()
+	fmt.Println("Restart Alma to activate the mnemon skill and hot-index hook.")
+	fmt.Println("Alma has no project-local hook config; this install is user-global.")
+	fmt.Println("Run 'mnemon setup --eject --target alma' to remove.")
+
+	return nil
+}
+
 // ─── Eject ──────────────────────────────────────────────────────────
 
 func runEjectFlow(envs []setup.Environment) error {
@@ -1666,6 +1736,12 @@ func ejectEnv(env *setup.Environment) error {
 		if len(errs) > 0 {
 			return errs[0]
 		}
+
+	case "alma":
+		errs := setup.AlmaEject(env.ConfigDir)
+		if len(errs) > 0 {
+			return errs[0]
+		}
 	}
 	return nil
 }

docs/USAGE.md

@@ -76,6 +76,7 @@ mnemon setup --target openclaw
 mnemon setup --target pi
 mnemon setup --target nanobot --global
 mnemon setup --target hermes
+mnemon setup --target alma
 
 # Auto-confirm all prompts (CI-friendly)
 mnemon setup --yes
@@ -87,8 +88,8 @@ mnemon setup --eject --target claude-code
 
 | Flag | Default | Description |
 |---|---|---|
-| `--global` | `false` | Install to user-wide config instead of project-local (required for ZCode lifecycle hooks; MiniMax Code installs to `~/.minimax/`; recommended for Nanobot: installs to `~/.nanobot/workspace/`; Pi installs to `~/.pi/agent/`; Hermes installs to `~/.hermes/`; QoderWork installs to `~/.qoderwork/`; Kimi Code installs to `~/.kimi-code/` or `$KIMI_CODE_HOME/`; OpenCode installs to `~/.config/opencode/`) |
-| `--target <name>` | (auto-detect) | Target environment: `claude-code`, `codex`, `cursor`, `zcode`, `minimax-code`, `trae`, `qoder`, `qoderwork`, `codebuddy`, `workbuddy`, `kimi`, `opencode`, `openclaw`, `nanobot`, `pi`, or `hermes` |
+| `--global` | `false` | Install to user-wide config instead of project-local (required for ZCode lifecycle hooks; MiniMax Code installs to `~/.minimax/`; recommended for Nanobot: installs to `~/.nanobot/workspace/`; Pi installs to `~/.pi/agent/`; Hermes installs to `~/.hermes/`; QoderWork installs to `~/.qoderwork/`; Kimi Code installs to `~/.kimi-code/` or `$KIMI_CODE_HOME/`; OpenCode installs to `~/.config/opencode/`; Alma always uses `~/.config/alma/`) |
+| `--target <name>` | (auto-detect) | Target environment: `claude-code`, `codex`, `cursor`, `zcode`, `minimax-code`, `trae`, `qoder`, `qoderwork`, `codebuddy`, `workbuddy`, `kimi`, `opencode`, `openclaw`, `nanobot`, `pi`, `hermes`, or `alma` |
 | `--eject` | `false` | Remove mnemon integrations |
 | `--yes` | `false` | Auto-confirm all prompts |
 

docs/zh/README.md

@@ -258,6 +258,22 @@ mnemon setup --target hermes --yes
 `on_session_start`、`pre_llm_call`、`post_llm_call`，以及可选的
 `on_session_finalize`。Hermes 可能会在首次运行时提示批准这些 shell hooks。
 
+### [Alma](https://alma.now)
+
+```bash
+mnemon setup --target alma --yes
+```
+
+一条命令将 mnemon skill、`mem` shim 和一个 `app.ready` hook 部署到
+`~/.config/alma/`。Alma 的 hook stdout 不会进入模型上下文——只消费最后一行
+JSON 里的 `decision`、`reason` 和 `updatedInput`——所以这个集成刻意与生命周期
+hook 类的目标不同：hook 只做一件事（刷新 `MEMORY.md` 里由 mnemon 生成的区块，
+Alma 本来就会把它注入每一轮的 system prompt），召回交给模型通过 skill 自行决定。
+区块由 `<!-- mnemon:begin -->` / `<!-- mnemon:end -->` 界定，标记之外的每个字节
+都原样保留，因为 Alma 自己的提示词也会让模型写同一个文件。
+
+Alma 没有项目级 hook 配置，因此该目标仅支持用户级安装。
+
 ### [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
 
 DeepSeek Harness（DSH）通过 [dsh-mnemon](https://github.com/omdsh-dev/dsh-mnemon) 插件集成：该插件把 DSH 的运行时热记忆、受管项目档案与 Mnemon 长期记忆体组织成一套受监督的三层记忆系统。

docs/zh/USAGE.md

@@ -71,6 +71,7 @@ mnemon setup --target openclaw
 mnemon setup --target pi
 mnemon setup --target nanobot --global
 mnemon setup --target hermes
+mnemon setup --target alma
 
 # 自动确认所有提示（CI 友好）
 mnemon setup --yes
@@ -82,8 +83,8 @@ mnemon setup --eject --target claude-code
 
 | 标志 | 默认值 | 说明 |
 |---|---|---|
-| `--global` | `false` | 安装到用户级配置而非项目本地（ZCode 生命周期 hooks 必须使用；MiniMax Code 安装到 `~/.minimax/`；Nanobot 推荐安装到 `~/.nanobot/workspace/`；Pi 安装到 `~/.pi/agent/`；Hermes 安装到 `~/.hermes/`；QoderWork 安装到 `~/.qoderwork/`；Kimi Code 安装到 `~/.kimi-code/` 或 `$KIMI_CODE_HOME/`；OpenCode 安装到 `~/.config/opencode/`） |
-| `--target <name>` | (自动检测) | 目标环境：`claude-code`、`codex`、`cursor`、`zcode`、`minimax-code`、`trae`、`qoder`、`qoderwork`、`codebuddy`、`workbuddy`、`kimi`、`opencode`、`openclaw`、`nanobot`、`pi` 或 `hermes` |
+| `--global` | `false` | 安装到用户级配置而非项目本地（ZCode 生命周期 hooks 必须使用；MiniMax Code 安装到 `~/.minimax/`；Nanobot 推荐安装到 `~/.nanobot/workspace/`；Pi 安装到 `~/.pi/agent/`；Hermes 安装到 `~/.hermes/`；QoderWork 安装到 `~/.qoderwork/`；Kimi Code 安装到 `~/.kimi-code/` 或 `$KIMI_CODE_HOME/`；OpenCode 安装到 `~/.config/opencode/`；Alma 固定使用 `~/.config/alma/`） |
+| `--target <name>` | (自动检测) | 目标环境：`claude-code`、`codex`、`cursor`、`zcode`、`minimax-code`、`trae`、`qoder`、`qoderwork`、`codebuddy`、`workbuddy`、`kimi`、`opencode`、`openclaw`、`nanobot`、`pi`、`hermes` 或 `alma` |
 | `--eject` | `false` | 移除 mnemon 集成 |
 | `--yes` | `false` | 自动确认所有提示 |