recallnest 1.4.1

package/integrations/claude-code/setup.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# RecallNest — Claude Code MCP setup (idempotent)
+# Usage: bash integrations/claude-code/setup.sh
+
+set -euo pipefail
+
+CLAUDE_JSON="$HOME/.claude.json"
+CLAUDE_MD="$HOME/.claude/CLAUDE.md"
+RECALLNEST_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+MCP_ENTRY="$RECALLNEST_DIR/src/mcp-server.ts"
+RULES_SNIPPET="$RECALLNEST_DIR/integrations/claude-code/claude-md-snippet.md"
+RULES_HELPER="$RECALLNEST_DIR/integrations/shared/install-managed-block.sh"
+
+# Verify mcp-server.ts exists
+if [[ ! -f "$MCP_ENTRY" ]]; then
+  echo "ERROR: $MCP_ENTRY not found. Run this from the recallnest repo root."
+  exit 1
+fi
+
+if [[ ! -f "$RULES_HELPER" ]]; then
+  echo "ERROR: $RULES_HELPER not found."
+  exit 1
+fi
+
+mkdir -p "$HOME/.claude"
+
+# Create ~/.claude.json if missing
+if [[ ! -f "$CLAUDE_JSON" ]]; then
+  echo '{}' > "$CLAUDE_JSON"
+  echo "Created $CLAUDE_JSON"
+fi
+
+# Check if recallnest MCP is already configured
+if bun -e "
+  const c = JSON.parse(require('fs').readFileSync('$CLAUDE_JSON','utf8'));
+  process.exit(c.mcpServers?.recallnest ? 0 : 1);
+" 2>/dev/null; then
+  echo "RecallNest MCP already configured in $CLAUDE_JSON — skipping."
+else
+  # Add recallnest to mcpServers using bun for safe JSON manipulation
+  bun -e "
+    const fs = require('fs');
+    const c = JSON.parse(fs.readFileSync('$CLAUDE_JSON','utf8'));
+    if (!c.mcpServers) c.mcpServers = {};
+    c.mcpServers.recallnest = {
+      command: 'bun',
+      args: ['run', '$MCP_ENTRY'],
+      env: {}
+    };
+    fs.writeFileSync('$CLAUDE_JSON', JSON.stringify(c, null, 2) + '\n');
+  "
+  echo "Added RecallNest MCP to $CLAUDE_JSON"
+fi
+
+. "$RULES_HELPER"
+install_managed_markdown_block "$RULES_SNIPPET" "$CLAUDE_MD" "recallnest-continuity"
+echo "Installed RecallNest continuity rules in $CLAUDE_MD"
+
+echo ""
+echo "Setup complete. Restart Claude Code to activate."
+echo ""
+echo "Continuity baseline seed:"
+echo "  (cd \"$RECALLNEST_DIR\" && bun run seed:continuity)"
+echo ""
+echo "Managed snippet source:"
+echo "  $RULES_SNIPPET"

package/integrations/claude-code/smoke-continuity.sh

@@ -0,0 +1,452 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+CLAUDE_BIN="${CLAUDE_BIN:-claude}"
+OUT_DIR="${RECALLNEST_CC_SMOKE_OUT_DIR:-/tmp/recallnest-claude-smoke-$(date +%Y%m%d-%H%M%S)}"
+OBSERVATION_SCOPE="${RECALLNEST_CC_SMOKE_SCOPE:-project:recallnest}"
+OBSERVATION_SOURCE="${RECALLNEST_CC_SMOKE_SOURCE:-smoke}"
+RECORD_OBSERVATIONS="${RECALLNEST_RECORD_WORKFLOW_OBSERVATIONS:-1}"
+
+CONTINUE_PROMPT="继续 RecallNest，不要让我重复前情。这个请求是 recall-only smoke：只调用 RecallNest continuity tools 恢复上下文，不要读 repo、不要运行 Bash、不要开始实际工作；如果当前 repo 状态未验证，就明确说 unknown，不要提 git status、未跟踪文件或修改文件名。恢复后只用一句话说明你接下来会做什么。"
+CHECKPOINT_PROMPT="继续 RecallNest，不要让我重复前情。这个请求是 recall-only smoke：只调用 RecallNest continuity tools 恢复上下文，不要读 repo、不要运行 Bash、不要开始实际工作；如果当前 repo 状态未验证，就明确说 unknown，不要提 git status、未跟踪文件或修改文件名；然后在结束前保存 checkpoint_session，并用两句话告诉我你保存了什么。"
+TASK_PIVOT_PROMPT="回到 RecallNest 项目，处理 task-pivot recall regression。这个请求是 recall-only smoke：只调用 RecallNest continuity tools 恢复相关记忆，不要读 repo、不要运行 Bash、不要开始实际工作；如果当前 repo 状态未验证，就明确说 unknown，不要提 git status、未跟踪文件或修改文件名。恢复后只用一句话说明你接下来会做什么。"
+REPO_TOOL_PATTERN='"name":"(Read|Bash|Grep|Glob)"'
+SEARCH_TOOL_PATTERN='"name":"mcp__recallnest__search_memory"'
+RESUME_TOOL_PATTERN='"name":"mcp__recallnest__resume_context"'
+RECALL_TOOL_PATTERN='"name":"mcp__recallnest__(resume_context|search_memory)"'
+REPO_STATE_PATTERN='git status|未提交|staged|uncommitted|已修改文件|modified files|untracked|新增文件|dirty repo|dirty worktree'
+REPO_STATE_CLAIM_PATTERN='git status (里|shows|showed)|未提交|staged|uncommitted|已修改文件|modified files|untracked|新增文件|dirty repo|dirty worktree|未跟踪'
+
+need_cmd() {
+  local cmd="$1"
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    echo "Missing required command: $cmd" >&2
+    exit 1
+  fi
+}
+
+log_step() {
+  local message="$1"
+  printf '[smoke] %s\n' "$message" >&2
+}
+
+record_workflow_observation() {
+  local workflow_id="$1"
+  local outcome="$2"
+  local summary="$3"
+  local signal="${4:-}"
+  local task="${5:-}"
+  local tools="${6:-}"
+
+  if [[ "$RECORD_OBSERVATIONS" == "0" ]]; then
+    return 0
+  fi
+
+  local cmd=(
+    bun run src/cli.ts workflow-observe
+    "$workflow_id"
+    "$summary"
+    --outcome "$outcome"
+    --scope "$OBSERVATION_SCOPE"
+    --source "$OBSERVATION_SOURCE"
+    --tags "continuity,claude-smoke"
+  )
+
+  if [[ -n "$signal" ]]; then
+    cmd+=(--signal "$signal")
+  fi
+  if [[ -n "$task" ]]; then
+    cmd+=(--task "$task")
+  fi
+  if [[ -n "$tools" ]]; then
+    cmd+=(--tools "$tools")
+  fi
+
+  (
+    cd "$ROOT_DIR"
+    "${cmd[@]}"
+  ) >/dev/null
+}
+
+record_and_fail() {
+  local workflow_id="$1"
+  local outcome="$2"
+  local summary="$3"
+  local signal="${4:-}"
+  local task="${5:-}"
+  local tools="${6:-}"
+
+  record_workflow_observation "$workflow_id" "$outcome" "$summary" "$signal" "$task" "$tools"
+  echo "FAIL: $summary" >&2
+  exit 1
+}
+
+first_match_line() {
+  local pattern="$1"
+  local file="$2"
+  rg -n --max-count 1 "$pattern" "$file" | cut -d: -f1 || true
+}
+
+run_case() {
+  local name="$1"
+  local allowed_tools="$2"
+  local prompt="$3"
+  local output_file="$OUT_DIR/$name.jsonl"
+
+  "$CLAUDE_BIN" \
+    -p \
+    --verbose \
+    --output-format stream-json \
+    --permission-mode dontAsk \
+    --allowedTools="$allowed_tools" \
+    "$prompt" >"$output_file"
+
+  echo "$output_file"
+}
+
+assert_no_permission_denials() {
+  local file="$1"
+  local workflow_id="$2"
+  local task="$3"
+  local tools="$4"
+  if rg -q '"permission_denials":\[\{' "$file"; then
+    record_and_fail \
+      "$workflow_id" \
+      "failure" \
+      "Claude Code smoke ${task} hit a permission denial before completing the RecallNest flow." \
+      "permission-denied" \
+      "$task" \
+      "$tools"
+  fi
+}
+
+assert_resume_before_repo_tools() {
+  local file="$1"
+  local task="$2"
+  local resume_line repo_tool_line
+
+  resume_line="$(first_match_line "$RESUME_TOOL_PATTERN" "$file")"
+  repo_tool_line="$(first_match_line "$REPO_TOOL_PATTERN" "$file")"
+
+  if [[ -z "$resume_line" ]]; then
+    record_and_fail \
+      "resume_context" \
+      "missed" \
+      "Claude Code smoke ${task} never called resume_context." \
+      "missing-resume-context" \
+      "$task" \
+      "resume_context"
+  fi
+
+  if [[ -n "$repo_tool_line" && "$repo_tool_line" -lt "$resume_line" ]]; then
+    record_and_fail \
+      "resume_context" \
+      "missed" \
+      "Claude Code smoke ${task} explored the repo before resume_context." \
+      "resume-after-repo-tool" \
+      "$task" \
+      "resume_context"
+  fi
+}
+
+assert_no_repo_tools() {
+  local file="$1"
+  local task="$2"
+
+  if rg -q "$REPO_TOOL_PATTERN" "$file"; then
+    record_and_fail \
+      "resume_context" \
+      "failure" \
+      "Claude Code smoke ${task} used repo tools during a recall-only flow." \
+      "repo-tool-in-recall-only" \
+      "$task" \
+      "resume_context,search_memory,checkpoint_session"
+  fi
+}
+
+assert_recall_before_repo_tools() {
+  local file="$1"
+  local task="$2"
+  local recall_line repo_tool_line
+
+  recall_line="$(first_match_line "$RECALL_TOOL_PATTERN" "$file")"
+  repo_tool_line="$(first_match_line "$REPO_TOOL_PATTERN" "$file")"
+
+  if [[ -z "$recall_line" ]]; then
+    record_and_fail \
+      "search_memory" \
+      "missed" \
+      "Claude Code smoke ${task} never called resume_context or search_memory." \
+      "missing-recall-tool" \
+      "$task" \
+      "resume_context,search_memory"
+  fi
+
+  if [[ -n "$repo_tool_line" && "$repo_tool_line" -lt "$recall_line" ]]; then
+    record_and_fail \
+      "search_memory" \
+      "missed" \
+      "Claude Code smoke ${task} explored the repo before any RecallNest recovery tool." \
+      "recall-after-repo-tool" \
+      "$task" \
+      "resume_context,search_memory"
+  fi
+}
+
+assert_resume_before_search_if_present() {
+  local file="$1"
+  local task="$2"
+  local resume_line search_line
+
+  resume_line="$(first_match_line "$RESUME_TOOL_PATTERN" "$file")"
+  search_line="$(first_match_line "$SEARCH_TOOL_PATTERN" "$file")"
+
+  if [[ -z "$search_line" ]]; then
+    return 0
+  fi
+
+  if [[ -z "$resume_line" ]]; then
+    record_and_fail \
+      "resume_context" \
+      "missed" \
+      "Claude Code smoke ${task} called search_memory without resume_context." \
+      "search-without-resume" \
+      "$task" \
+      "resume_context,search_memory"
+  fi
+
+  if [[ "$search_line" -lt "$resume_line" ]]; then
+    record_and_fail \
+      "resume_context" \
+      "failure" \
+      "Claude Code smoke ${task} called search_memory before resume_context." \
+      "search-before-resume" \
+      "$task" \
+      "resume_context,search_memory"
+  fi
+}
+
+first_recall_tool() {
+  local file="$1"
+  local resume_line search_line
+
+  resume_line="$(first_match_line "$RESUME_TOOL_PATTERN" "$file")"
+  search_line="$(first_match_line "$SEARCH_TOOL_PATTERN" "$file")"
+
+  if [[ -n "$resume_line" && ( -z "$search_line" || "$resume_line" -le "$search_line" ) ]]; then
+    echo "resume_context"
+    return
+  fi
+  if [[ -n "$search_line" ]]; then
+    echo "search_memory"
+    return
+  fi
+  echo "recall"
+}
+
+describe_unverified_repo_state_claim_sources() {
+  local file="$1"
+  local repo_tool_line assistant_line checkpoint_request_line checkpoint_saved_line
+  local sources=()
+
+  repo_tool_line="$(first_match_line "$REPO_TOOL_PATTERN" "$file")"
+  if [[ -n "$repo_tool_line" ]]; then
+    return 0
+  fi
+
+  assistant_line="$(first_match_line "\"type\":\"assistant\".*\"type\":\"text\".*($REPO_STATE_CLAIM_PATTERN)" "$file")"
+  checkpoint_request_line="$(first_match_line "\"name\":\"mcp__recallnest__checkpoint_session\".*($REPO_STATE_CLAIM_PATTERN)" "$file")"
+  checkpoint_saved_line="$(first_match_line "Checkpoint [0-9a-f]+.*($REPO_STATE_CLAIM_PATTERN)" "$file")"
+  if [[ -n "$assistant_line" ]]; then
+    sources+=("assistant:$assistant_line")
+  fi
+  if [[ -n "$checkpoint_request_line" ]]; then
+    sources+=("checkpoint_request:$checkpoint_request_line")
+  fi
+  if [[ -n "$checkpoint_saved_line" ]]; then
+    sources+=("checkpoint_saved:$checkpoint_saved_line")
+  fi
+
+  if [[ ${#sources[@]} -gt 0 ]]; then
+    printf '%s\n' "${sources[*]}"
+  fi
+}
+
+assert_no_unverified_repo_state_claims() {
+  local file="$1"
+  local task="$2"
+  local sources
+
+  sources="$(describe_unverified_repo_state_claim_sources "$file")"
+  if [[ -n "$sources" ]]; then
+    record_and_fail \
+      "resume_context" \
+      "failure" \
+      "Claude Code smoke ${task} restated unverified repo-state details during a recall-only flow." \
+      "unverified-repo-state-claim" \
+      "$task" \
+      "resume_context,search_memory,checkpoint_session"
+  fi
+}
+
+assert_checkpoint_repo_state_claims_are_verified() {
+  local file="$1"
+  local task="$2"
+  local checkpoint_saved_line
+
+  checkpoint_saved_line="$(first_match_line "Checkpoint [0-9a-f]+.*($REPO_STATE_PATTERN)" "$file")"
+  if [[ -n "$checkpoint_saved_line" ]] && ! rg -q "$REPO_TOOL_PATTERN" "$file"; then
+    record_and_fail \
+      "checkpoint_session" \
+      "failure" \
+      "Claude Code smoke ${task} saved repo-state text into checkpoint_session without visible repo verification." \
+      "repo-state-contamination" \
+      "$task" \
+      "resume_context,checkpoint_session"
+  fi
+}
+
+extract_checkpoint_id() {
+  local file="$1"
+  rg -o --max-count 1 'Checkpoint [0-9a-f]{8,}' "$file" | awk '{print $2}' || true
+}
+
+summarize_case() {
+  local label="$1"
+  local file="$2"
+  local resume_line recall_line checkpoint_line repo_tool_line checkpoint_id repo_state_sources
+
+  resume_line="$(first_match_line "$RESUME_TOOL_PATTERN" "$file")"
+  recall_line="$(first_match_line "$RECALL_TOOL_PATTERN" "$file")"
+  checkpoint_line="$(first_match_line '"name":"mcp__recallnest__checkpoint_session"' "$file")"
+  repo_tool_line="$(first_match_line "$REPO_TOOL_PATTERN" "$file")"
+  checkpoint_id="$(extract_checkpoint_id "$file")"
+  repo_state_sources="$(describe_unverified_repo_state_claim_sources "$file")"
+
+  echo "$label"
+  echo "  log: $file"
+  echo "  resume_context line: ${resume_line:-missing}"
+  echo "  first recall tool line: ${recall_line:-missing}"
+  if [[ -n "$repo_tool_line" ]]; then
+    echo "  first repo tool line: $repo_tool_line"
+  else
+    echo "  first repo tool line: none"
+  fi
+  if [[ -n "$checkpoint_line" ]]; then
+    echo "  checkpoint_session line: $checkpoint_line"
+  fi
+  if [[ -n "$checkpoint_id" ]]; then
+    echo "  checkpoint id: $checkpoint_id"
+  fi
+  if [[ -n "$repo_state_sources" ]]; then
+    echo "  unverified repo-state sources: $repo_state_sources"
+  fi
+}
+
+need_cmd "$CLAUDE_BIN"
+need_cmd rg
+need_cmd bun
+
+mkdir -p "$OUT_DIR"
+
+continue_log="$(
+  cd "$ROOT_DIR" && \
+    log_step "Running continue case..."
+    run_case \
+      "continue" \
+      "ToolSearch,mcp__recallnest__resume_context,mcp__recallnest__search_memory" \
+      "$CONTINUE_PROMPT"
+)"
+
+assert_no_permission_denials "$continue_log" "resume_context" "claude-code smoke continue" "resume_context,search_memory"
+assert_resume_before_repo_tools "$continue_log" "claude-code smoke continue"
+assert_resume_before_search_if_present "$continue_log" "claude-code smoke continue"
+assert_no_repo_tools "$continue_log" "claude-code smoke continue"
+assert_no_unverified_repo_state_claims "$continue_log" "claude-code smoke continue"
+record_workflow_observation \
+  "resume_context" \
+  "success" \
+  "Claude Code smoke continue case recovered continuity before any visible repo tools." \
+  "startup-recovered" \
+  "claude-code smoke continue" \
+  "resume_context,search_memory"
+
+checkpoint_log="$(
+  cd "$ROOT_DIR" && \
+    log_step "Running checkpoint case..."
+    run_case \
+      "checkpoint" \
+      "ToolSearch,mcp__recallnest__resume_context,mcp__recallnest__search_memory,mcp__recallnest__checkpoint_session" \
+      "$CHECKPOINT_PROMPT"
+)"
+
+assert_no_permission_denials "$checkpoint_log" "resume_context" "claude-code smoke checkpoint" "resume_context,search_memory,checkpoint_session"
+assert_resume_before_repo_tools "$checkpoint_log" "claude-code smoke checkpoint"
+assert_resume_before_search_if_present "$checkpoint_log" "claude-code smoke checkpoint"
+assert_no_repo_tools "$checkpoint_log" "claude-code smoke checkpoint"
+assert_no_unverified_repo_state_claims "$checkpoint_log" "claude-code smoke checkpoint"
+
+resume_line="$(first_match_line '"name":"mcp__recallnest__resume_context"' "$checkpoint_log")"
+checkpoint_line="$(first_match_line '"name":"mcp__recallnest__checkpoint_session"' "$checkpoint_log")"
+
+if [[ -z "$checkpoint_line" ]]; then
+  record_and_fail \
+    "checkpoint_session" \
+    "missed" \
+    "Claude Code smoke checkpoint case never called checkpoint_session." \
+    "missing-checkpoint-session" \
+    "claude-code smoke checkpoint" \
+    "resume_context,search_memory,checkpoint_session"
+fi
+
+if [[ "$checkpoint_line" -lt "$resume_line" ]]; then
+  record_and_fail \
+    "checkpoint_session" \
+    "failure" \
+    "Claude Code smoke checkpoint case called checkpoint_session before resume_context." \
+    "checkpoint-before-resume" \
+    "claude-code smoke checkpoint" \
+    "resume_context,search_memory,checkpoint_session"
+fi
+
+assert_checkpoint_repo_state_claims_are_verified "$checkpoint_log" "claude-code smoke checkpoint"
+record_workflow_observation \
+  "checkpoint_session" \
+  "success" \
+  "Claude Code smoke checkpoint case saved a clean checkpoint after continuity recovery." \
+  "checkpoint-saved-cleanly" \
+  "claude-code smoke checkpoint" \
+  "resume_context,search_memory,checkpoint_session"
+
+task_pivot_log="$(
+  cd "$ROOT_DIR" && \
+    log_step "Running task-pivot case..."
+    run_case \
+      "task-pivot" \
+      "ToolSearch,mcp__recallnest__resume_context,mcp__recallnest__search_memory" \
+      "$TASK_PIVOT_PROMPT"
+)"
+
+assert_no_permission_denials "$task_pivot_log" "search_memory" "claude-code smoke task-pivot" "resume_context,search_memory"
+assert_recall_before_repo_tools "$task_pivot_log" "claude-code smoke task-pivot"
+assert_resume_before_search_if_present "$task_pivot_log" "claude-code smoke task-pivot"
+assert_no_repo_tools "$task_pivot_log" "claude-code smoke task-pivot"
+assert_no_unverified_repo_state_claims "$task_pivot_log" "claude-code smoke task-pivot"
+record_workflow_observation \
+  "$(first_recall_tool "$task_pivot_log")" \
+  "success" \
+  "Claude Code smoke task-pivot case recovered RecallNest context before any visible repo tools." \
+  "task-pivot-recovered" \
+  "claude-code smoke task-pivot" \
+  "resume_context,search_memory"
+
+echo "Claude Code continuity smoke passed."
+echo "Artifacts saved under: $OUT_DIR"
+if [[ "$RECORD_OBSERVATIONS" != "0" ]]; then
+  echo "Workflow observations stored under scope: $OBSERVATION_SCOPE"
+fi
+summarize_case "Continue case:" "$continue_log"
+summarize_case "Checkpoint case:" "$checkpoint_log"
+summarize_case "Task-pivot case:" "$task_pivot_log"

package/integrations/codex/README.md

@@ -0,0 +1,49 @@
+# Codex Integration
+
+> Codex 接入指南：一键配 MCP + continuity 规则，让 Codex 在新窗口里主动恢复稳定上下文。
+
+## Quick Start
+
+```bash
+bash integrations/codex/setup.sh
+```
+
+## What It Does
+
+- Adds RecallNest as an MCP server in `~/.codex/config.toml`
+- Installs a managed RecallNest block in `~/.codex/AGENTS.md`
+
+## Continuity Rules
+
+The managed block comes from [agents-md-snippet.md](agents-md-snippet.md) and tells Codex to:
+
+- call `resume_context` at the start of fresh windows or continuity-sensitive tasks
+- run lightweight `search_memory` on task pivots inside the same project before repo exploration drifts
+- reuse known `scope` / `sessionId` and the resolved scope returned by `resume_context` in follow-up recall calls
+- treat recalled or startup-hook repo state as unverified until this window explicitly checks the repo
+- save `checkpoint_session` before leaving resumable work
+- do not inspect repo state just to enrich a close-window checkpoint unless the user explicitly asked for repo state
+- do not write unverified repo-state claims into `checkpoint_session`
+- capture durable facts with `store_memory` and reusable workflows with `store_workflow_pattern`
+
+## Manual Setup
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.recallnest]
+command = "bun"
+args = ["run", "RECALLNEST_PATH/src/mcp-server.ts"]
+```
+
+Replace `RECALLNEST_PATH` with your actual path.
+
+Then copy [agents-md-snippet.md](agents-md-snippet.md) into `~/.codex/AGENTS.md` or your repo-level `AGENTS.md`.
+
+## Shared Index
+
+Same LanceDB index as Claude Code and Gemini CLI — all three share memories.
+
+## Verify
+
+Start Codex and ask: "resume my context for RecallNest continuity work"

package/integrations/codex/agents-md-snippet.md

@@ -0,0 +1,31 @@
+## RecallNest Continuity
+
+- These continuity rules override later generic writing, skill, and local-memory instructions whenever the user's intent is continuity recovery or memory recall.
+- If the user says `continue`, `继续`, `接着`, `刚才`, `上个窗口`, `不要让我重复前情`, `之前讨论过`, or asks what the project is solving / where it stopped / what to do next, call `resume_context` before any Bash, Read, or repo exploration.
+- If the user starts a concrete task in an active project, shifts back to a named project, or asks for prior implementation detail, do lightweight RecallNest recovery before repo exploration even without an explicit `continue`: call `resume_context` when you need broad continuity, or `search_memory` when you just need a focused fact/pattern recall.
+- Do not substitute `git status`, `git log`, or reading local docs for `resume_context`. Local inspection can validate current code state only after continuity has been recovered.
+- Use `resume_context` to recover stable background such as active projects, durable preferences, recent cases, reusable patterns, and the latest checkpoint.
+- When `scope`, shared project scope, or `sessionId` is known, pass it into `resume_context` / `search_memory` / related recall tools instead of relying on global recall.
+- If `resume_context` returns a resolved scope or latest checkpoint scope, reuse that same scope in follow-up `search_memory`, `brief_memory`, `pin_memory`, and other recall calls.
+- If `resume_context` or a recalled checkpoint mentions repo state such as `git status`, modified files, untracked files, commits, or pending push, treat that as handoff context only. Do not restate it as the current repo state unless you verify it in this window with repo tools.
+- If current repo state has not been verified in this window, say it is unknown or omit it. Do not infer dirty/clean state, staged files, commit readiness, or specific modified files from recalled context alone.
+- In recall-only continuity recovery, do not mention `git status`, modified/untracked filenames, or repo cleanliness just to sound specific. If the next step would need repo inspection, say you would inspect the repo after the user asks you to proceed.
+- Treat startup hooks, restored checkpoints, and recalled notes the same way: unless this window explicitly inspected the repo, they are not evidence for current file lists or worktree state.
+- If the user is asking what you remember about preferences, style, tone, identity, or current project background, answer from `resume_context` and recalled memory first. Do not read repo files or local docs unless the user explicitly asks for file inspection or the recovered context is insufficient.
+- If the message mentions writing, articles, or the public account but the actual intent is recall-only (for example: "what style do you remember", "哪些表达方式要避免", "回忆偏好"), do not activate article-writing workflows, writing-persona files, or content-alchemy style skills. Treat it as a memory recall question unless the user explicitly asks you to draft, edit, or research.
+- Normal writing requests are unchanged: if the user explicitly asks you to draft an article, revise copy, research a topic, or continue the writing pipeline, you should use the existing writing workflows and skills as usual.
+- For recall-only writing/style questions, do not supplement the answer with local memory indexes, quick-reference blocks, `writing-persona.md`, `writing-rules.md`, or similar local style docs. If RecallNest recalled only one preference, answer from that one preference.
+- For recall-only preference questions, prefer a plain `resume_context` call over writing-specific profiles or broader rulesets unless the user explicitly asks for the full writing system.
+- If `resume_context` returns `Response mode: recall-only` or a recall-only guidance line, follow it literally. Restate the recalled stable context briefly and do not add extra examples, banned words, or inferred style rules unless they were also recalled.
+- If `resume_context` already returns a relevant durable preference for the current task, keep the answer narrow. Do not pad it with older pins, briefs, or local rule files unless the user asks for a broader ruleset.
+- For recall-only questions, stay constrained to the recalled items. Do not expand one recalled preference into a full doctrine, banned-word list, or writing system unless those details were also recalled or the user explicitly asks for expansion.
+- If recalled context is sparse, say what you do remember and what is still uncertain. Do not invent extra rules to sound complete.
+- For task pivots or fresh implementation work inside the same project, run a lightweight `search_memory` using 2-3 key nouns or verbs from the user's request before repo exploration drifts.
+- If `resume_context` is not enough and you need a specific fact, follow up with `search_memory` using 2-3 key nouns or verbs instead of full sentences.
+- If the user explicitly corrects a continuity miss, such as saying you should have resumed context first or should have saved a checkpoint before stopping, fix the workflow first and then call `workflow_observe` with outcome `corrected` so the miss is tracked outside durable memory.
+- Before leaving a window with unfinished or resumable work, call `checkpoint_session` and capture the current summary, decisions, open loops, next actions, and relevant entities.
+- Do not inspect repo state just to make `checkpoint_session` more complete unless the user explicitly asked for repo state in this window. A close-window handoff should prefer an incomplete but verified checkpoint over speculative or freshly-probed repo details.
+- Do not write repo-state claims into `checkpoint_session` unless you actually inspected the repo in this window. A recalled checkpoint mentioning dirty files or pending push is not enough evidence to repeat or persist it.
+- Do not copy or paraphrase unverified repo-state text into `checkpoint_session`, even with caveats like `未在本窗口验证`, `上次看到`, or `according to the earlier checkpoint`. If this window never inspected the repo, omit repo state entirely from the checkpoint.
+- Use `store_memory` when you learn durable profile, preference, entity, or case knowledge that should survive across future windows.
+- Use `store_workflow_pattern` when you discover a reusable multi-step workflow that should become durable `patterns` memory.

package/integrations/codex/setup.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# RecallNest — Codex MCP setup (idempotent)
+# Usage: bash integrations/codex/setup.sh
+
+set -euo pipefail
+
+CODEX_CONFIG="$HOME/.codex/config.toml"
+CODEX_AGENTS="$HOME/.codex/AGENTS.md"
+CODEX_DIR="$HOME/.codex"
+RECALLNEST_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+MCP_ENTRY="$RECALLNEST_DIR/src/mcp-server.ts"
+RULES_SNIPPET="$RECALLNEST_DIR/integrations/codex/agents-md-snippet.md"
+RULES_HELPER="$RECALLNEST_DIR/integrations/shared/install-managed-block.sh"
+
+if [[ ! -f "$MCP_ENTRY" ]]; then
+  echo "ERROR: $MCP_ENTRY not found. Run this from the recallnest repo root."
+  exit 1
+fi
+
+if [[ ! -f "$RULES_HELPER" ]]; then
+  echo "ERROR: $RULES_HELPER not found."
+  exit 1
+fi
+
+# Create ~/.codex/ if missing
+mkdir -p "$CODEX_DIR"
+
+# Create config.toml if missing
+if [[ ! -f "$CODEX_CONFIG" ]]; then
+  touch "$CODEX_CONFIG"
+  echo "Created $CODEX_CONFIG"
+fi
+
+# Check if already configured
+if grep -q '\[mcp_servers\.recallnest\]' "$CODEX_CONFIG" 2>/dev/null; then
+  echo "RecallNest MCP already configured in $CODEX_CONFIG — skipping."
+else
+  cat >> "$CODEX_CONFIG" <<EOF
+
+[mcp_servers.recallnest]
+command = "bun"
+args = ["run", "$MCP_ENTRY"]
+EOF
+  echo "Added RecallNest MCP to $CODEX_CONFIG"
+fi
+
+. "$RULES_HELPER"
+install_managed_markdown_block "$RULES_SNIPPET" "$CODEX_AGENTS" "recallnest-continuity"
+echo "Installed RecallNest continuity rules in $CODEX_AGENTS"
+
+echo ""
+echo "Setup complete. Restart Codex to activate."
+echo ""
+echo "Continuity baseline seed:"
+echo "  (cd \"$RECALLNEST_DIR\" && bun run seed:continuity)"
+echo ""
+echo "Managed snippet source:"
+echo "  $RULES_SNIPPET"