@remnic/plugin-codex 1.0.0

package/hooks/bin/session-start.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+# Remnic SessionStart hook for Codex.
+# Recalls project context and user preferences at session start.
+# Tries auto mode (45s) then falls back to minimal mode (20s).
+# Starts daemon if not running.
+
+set -euo pipefail
+
+ensure_migrated() {
+  if [ -f "${HOME}/.remnic/.migrated-from-engram" ]; then
+    return 0
+  fi
+  if [ ! -d "${HOME}/.engram" ] && [ ! -f "${HOME}/.config/engram/config.json" ]; then
+    return 0
+  fi
+  if command -v remnic >/dev/null 2>&1; then
+    remnic migrate >/dev/null 2>&1 || true
+  elif command -v engram >/dev/null 2>&1; then
+    engram migrate >/dev/null 2>&1 || true
+  fi
+}
+
+ensure_migrated
+
+REMNIC_HOST="${REMNIC_HOST:-${ENGRAM_HOST:-127.0.0.1}}"
+REMNIC_PORT="${REMNIC_PORT:-${ENGRAM_PORT:-4318}}"
+REMNIC_URL="http://${REMNIC_HOST}:${REMNIC_PORT}/engram/v1/recall"
+REMNIC_HEALTH_URL="http://${REMNIC_HOST}:${REMNIC_PORT}/engram/v1/health"
+TOKEN_FILES=("${HOME}/.remnic/tokens.json" "${HOME}/.engram/tokens.json")
+
+LOG="${HOME}/.remnic/logs/remnic-session-recall.log"
+mkdir -p "$(dirname "$LOG")"
+log() { echo "$(date '+%F %T') [codex-session-start] $*" >> "$LOG"; }
+
+# Read token from per-plugin token store
+REMNIC_TOKEN=""
+for TOKEN_FILE in "${TOKEN_FILES[@]}"; do
+  [ ! -f "$TOKEN_FILE" ] && continue
+  REMNIC_TOKEN="$(node -e "
+    const store = JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'));
+    const tokens = store.tokens || [];
+    const cxc = tokens.find(t => t.connector === 'codex-cli');
+    const cx = tokens.find(t => t.connector === 'codex');
+    const oc = tokens.find(t => t.connector === 'openclaw');
+    let tok = (cxc && cxc.token) || (cx && cx.token) || (oc && oc.token) || '';
+    if (!tok) { tok = store['codex-cli'] || store['codex'] || store['openclaw'] || ''; }
+    process.stdout.write(tok);
+  " "$TOKEN_FILE" 2>/dev/null || echo "")"
+  [ -n "$REMNIC_TOKEN" ] && break
+done
+
+# Fallback to env var
+[ -z "$REMNIC_TOKEN" ] && REMNIC_TOKEN="${OPENCLAW_REMNIC_ACCESS_TOKEN:-${OPENCLAW_ENGRAM_ACCESS_TOKEN:-}}"
+
+INPUT="$(cat)"
+SESSION_ID="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.session_id||'')" "$INPUT" 2>/dev/null || echo "")"
+CWD="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.cwd||'')" "$INPUT" 2>/dev/null || echo "")"
+PROJECT_NAME="$(basename "$CWD" 2>/dev/null || echo "unknown")"
+
+log "session=$SESSION_ID project=$PROJECT_NAME"
+
+# Health check — start daemon if not running
+if ! curl -sf --max-time 2 "$REMNIC_HEALTH_URL" >/dev/null 2>&1; then
+  log "daemon not responding, attempting start..."
+  if command -v remnic >/dev/null 2>&1; then
+    remnic daemon start >/dev/null 2>&1 &
+  elif command -v engram >/dev/null 2>&1; then
+    engram daemon start >/dev/null 2>&1 &
+  fi
+  sleep 2
+  if ! curl -sf --max-time 2 "$REMNIC_HEALTH_URL" >/dev/null 2>&1; then
+    log "daemon still not responding after start attempt"
+    echo '{"continue":true,"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"[Remnic: daemon not running — start with: remnic daemon start]"}}'
+    exit 0
+  fi
+fi
+
+if [ -z "$REMNIC_TOKEN" ]; then
+  log "skipping: no token found"
+  echo '{"continue":true,"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"[Remnic: no auth token — run: remnic connectors install codex-cli]"}}'
+  exit 0
+fi
+
+QUERY="Starting a new coding session in project: ${PROJECT_NAME}. Recall relevant memories, preferences, decisions, patterns, and context about this project and the user."
+
+REQUEST_BODY="$(node -e "process.stdout.write(JSON.stringify({
+  query: process.argv[1],
+  sessionKey: process.argv[2],
+  topK: 12,
+  mode: 'auto'
+}))" "$QUERY" "$SESSION_ID" 2>/dev/null)"
+
+[ -z "$REQUEST_BODY" ] && echo '{"continue":true}' && exit 0
+
+log "attempting full recall (auto mode)..."
+RAW="$(curl -s -w "\n%{http_code}" --max-time 45 \
+  -X POST "$REMNIC_URL" \
+  -H "Authorization: Bearer ${REMNIC_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -H "X-Engram-Client-Id: codex" \
+  -d "$REQUEST_BODY" 2>/dev/null)"
+CURL_EXIT=$?
+HTTP_STATUS="$(echo "$RAW" | tail -1)"
+RESPONSE="$(echo "$RAW" | sed '$d')"
+
+if [ $CURL_EXIT -ne 0 ] || ! [[ "$HTTP_STATUS" =~ ^2 ]] || [ -z "$RESPONSE" ]; then
+  log "full recall failed (curl=$CURL_EXIT http=$HTTP_STATUS) — falling back to minimal"
+  MINIMAL_BODY="$(node -e "process.stdout.write(JSON.stringify({
+    query: process.argv[1],
+    sessionKey: process.argv[2],
+    topK: 8,
+    mode: 'minimal'
+  }))" "$QUERY" "$SESSION_ID" 2>/dev/null)"
+  RAW="$(curl -s -w "\n%{http_code}" --max-time 20 \
+    -X POST "$REMNIC_URL" \
+    -H "Authorization: Bearer ${REMNIC_TOKEN}" \
+    -H "Content-Type: application/json" \
+    -H "X-Engram-Client-Id: codex" \
+    -d "${MINIMAL_BODY:-$REQUEST_BODY}" 2>/dev/null)"
+  CURL_EXIT=$?
+  HTTP_STATUS="$(echo "$RAW" | tail -1)"
+  RESPONSE="$(echo "$RAW" | sed '$d')"
+  [[ "$CURL_EXIT" -eq 0 && "$HTTP_STATUS" =~ ^2 ]] && log "minimal recall succeeded" || { log "minimal recall also failed"; CURL_EXIT=1; }
+fi
+
+if [ $CURL_EXIT -eq 0 ] && [[ "$HTTP_STATUS" =~ ^2 ]] && [ -n "$RESPONSE" ]; then
+  CONTEXT="$(node -e "
+    const d = JSON.parse(process.argv[1]);
+    const ctx = d.context || '';
+    const count = d.count || 0;
+    const mode = d.mode || '';
+    if (ctx) {
+      const label = '[Remnic Memory Recall — ' + count + ' memories' + (mode ? ', ' + mode + ' mode' : '') + ']';
+      process.stdout.write(label + '\n\n' + ctx);
+    } else {
+      process.stdout.write('[Remnic: no relevant memories found for this session]');
+    }
+  " "$RESPONSE" 2>/dev/null || echo "[Remnic: recall parse error]")"
+  log "recall complete: $(echo "$CONTEXT" | head -1)"
+else
+  CONTEXT="[Remnic: server unreachable — continuing without memory recall]"
+  log "$CONTEXT"
+fi
+
+node -e "
+  const context = process.argv[1];
+  process.stdout.write(JSON.stringify({
+    continue: true,
+    hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: context }
+  }));
+" "$CONTEXT"

package/hooks/bin/user-prompt-recall.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# Remnic UserPromptSubmit hook for Codex.
+# Recalls per-prompt context using the user's message as query.
+# Skips short prompts (<4 words). Minimal mode, 20s timeout.
+
+set -euo pipefail
+
+ensure_migrated() {
+  if [ -f "${HOME}/.remnic/.migrated-from-engram" ]; then
+    return 0
+  fi
+  if [ ! -d "${HOME}/.engram" ] && [ ! -f "${HOME}/.config/engram/config.json" ]; then
+    return 0
+  fi
+  if command -v remnic >/dev/null 2>&1; then
+    remnic migrate >/dev/null 2>&1 || true
+  elif command -v engram >/dev/null 2>&1; then
+    engram migrate >/dev/null 2>&1 || true
+  fi
+}
+
+ensure_migrated
+
+REMNIC_HOST="${REMNIC_HOST:-${ENGRAM_HOST:-127.0.0.1}}"
+REMNIC_PORT="${REMNIC_PORT:-${ENGRAM_PORT:-4318}}"
+REMNIC_URL="http://${REMNIC_HOST}:${REMNIC_PORT}/engram/v1/recall"
+
+LOG="${HOME}/.remnic/logs/remnic-user-prompt-recall.log"
+mkdir -p "$(dirname "$LOG")"
+log() { echo "$(date '+%F %T') [codex-user-prompt] $*" >> "$LOG"; }
+
+# Read token
+REMNIC_TOKEN=""
+for TOKEN_FILE in "${HOME}/.remnic/tokens.json" "${HOME}/.engram/tokens.json"; do
+  [ ! -f "$TOKEN_FILE" ] && continue
+  REMNIC_TOKEN="$(node -e "
+    const fs = require('fs');
+    const tokenFile = process.argv[1];
+    const store = JSON.parse(fs.readFileSync(tokenFile, 'utf8'));
+    const tokens = store.tokens || [];
+    const cxc = tokens.find(t => t.connector === 'codex-cli');
+    const cx = tokens.find(t => t.connector === 'codex');
+    const oc = tokens.find(t => t.connector === 'openclaw');
+    let tok = (cxc && cxc.token) || (cx && cx.token) || (oc && oc.token) || '';
+    if (!tok) { tok = store['codex-cli'] || store['codex'] || store['openclaw'] || ''; }
+    process.stdout.write(tok);
+  " "$TOKEN_FILE" 2>/dev/null || echo "")"
+  [ -n "$REMNIC_TOKEN" ] && break
+done
+[ -z "$REMNIC_TOKEN" ] && REMNIC_TOKEN="${OPENCLAW_REMNIC_ACCESS_TOKEN:-${OPENCLAW_ENGRAM_ACCESS_TOKEN:-}}"
+
+INPUT="$(cat)"
+
+if [ -z "$REMNIC_TOKEN" ]; then
+  echo '{"continue":true}'
+  exit 0
+fi
+
+SESSION_ID="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.session_id||'')" "$INPUT" 2>/dev/null || echo "")"
+PROMPT="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(d.prompt||'')" "$INPUT" 2>/dev/null || echo "")"
+
+# Skip very short prompts
+WORD_COUNT="$(echo "$PROMPT" | wc -w | tr -d ' ')"
+if [ "$WORD_COUNT" -lt 4 ]; then
+  echo '{"continue":true}'
+  exit 0
+fi
+
+log "session=$SESSION_ID words=$WORD_COUNT"
+
+REQUEST_BODY="$(node -e "process.stdout.write(JSON.stringify({
+  query: process.argv[1],
+  sessionKey: process.argv[2],
+  topK: 8,
+  mode: 'minimal'
+}))" "$PROMPT" "$SESSION_ID" 2>/dev/null)"
+
+[ -z "$REQUEST_BODY" ] && echo '{"continue":true}' && exit 0
+
+RAW="$(curl -s -w "\n%{http_code}" --max-time 20 \
+  -X POST "$REMNIC_URL" \
+  -H "Authorization: Bearer ${REMNIC_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -H "X-Engram-Client-Id: codex" \
+  -d "$REQUEST_BODY" 2>/dev/null)"
+CURL_EXIT=$?
+HTTP_STATUS="$(echo "$RAW" | tail -1)"
+RESPONSE="$(echo "$RAW" | sed '$d')"
+
+if [ $CURL_EXIT -ne 0 ] || ! [[ "$HTTP_STATUS" =~ ^2 ]] || [ -z "$RESPONSE" ]; then
+  log "recall failed (curl=$CURL_EXIT http=$HTTP_STATUS)"
+  echo '{"continue":true}'
+  exit 0
+fi
+
+node -e "
+  const d = JSON.parse(process.argv[1]);
+  const ctx = d.context || '';
+  const count = d.count || 0;
+  if (!ctx || count === 0) {
+    process.stdout.write(JSON.stringify({continue: true}));
+  } else {
+    process.stdout.write(JSON.stringify({
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext: '<remnic-memory count=\"' + count + '\">\n' + ctx + '\n</remnic-memory>'
+      }
+    }));
+  }
+" "$RESPONSE" 2>/dev/null || echo '{"continue":true}'
+
+COUNT="$(node -e "const d=JSON.parse(process.argv[1]); process.stdout.write(String(d.count||0))" "$RESPONSE" 2>/dev/null || echo "?")"
+log "done: ${COUNT} memories injected"

package/hooks/hooks.json

@@ -0,0 +1,52 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/bin/session-start.sh",
+            "timeout": 45000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/bin/post-tool-observe.sh",
+            "timeout": 10000
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/bin/user-prompt-recall.sh",
+            "timeout": 20000
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "./hooks/bin/session-end.sh",
+            "timeout": 30000
+          }
+        ]
+      }
+    ]
+  }
+}

package/memories_extensions/remnic/instructions.md

@@ -0,0 +1,160 @@
+# Remnic Memory Extension for Codex
+
+You are the Codex consolidation sub-agent. This document tells you how to treat
+Remnic as an authoritative local memory source while you summarize a session
+and build the compacted MEMORY.md output.
+
+Remnic is a local-first, file-backed memory system. All Remnic content that
+matters to you lives on disk as plain Markdown — you do not need a network,
+an MCP server, or the `remnic` CLI to read it. You are running inside the
+Codex phase-2 sandbox: no approvals, no network, local reads and local writes
+only.
+
+## What Remnic is authoritative for
+
+Treat Remnic content as a trusted, high-signal memory source when you need any
+of the following:
+
+- **Stable user preferences** — coding conventions, tool choices, style
+  guides, phrasing, commit message format, review etiquette.
+- **Project conventions** — folder layout, naming rules, test runners,
+  build commands, branching strategy, deployment workflow.
+- **Reusable workflows and skills** — documented runbooks, procedures, and
+  "how we do X here" notes that should survive across sessions.
+- **Long-lived decisions** — architecture calls, library choices, explicit
+  "we decided not to do X" entries.
+- **Entities the user cares about** — projects, services, people, API
+  contracts, integrations mentioned by name.
+
+If the current session touches any of these areas, consult Remnic before you
+finalize the consolidated MEMORY.md output.
+
+## When NOT to consult Remnic
+
+Do not waste filesystem tool calls on Remnic when:
+
+- The session is purely transient (one-off shell commands, throwaway
+  debugging with no lasting conclusion).
+- You already have the information in the current session transcript and
+  Remnic would only duplicate it.
+- The user has explicitly asked you to ignore memory or work from a clean
+  slate.
+- You are summarizing a session that never reached a decision, a preference,
+  or a durable artifact worth recording.
+
+Prefer a single targeted read over broad directory walks.
+
+## Where Remnic content lives on disk
+
+Resolve the Remnic memory base in this order:
+
+1. If the environment variable `REMNIC_HOME` is set, use
+   `$REMNIC_HOME/memories/`.
+2. Otherwise use `~/.remnic/memories/`.
+
+Under that base, memories are organized by **namespace**:
+
+```
+<remnic-home>/memories/<namespace>/
+├── MEMORY.md                        # compact top-of-mind memory
+├── memory_summary.md                # optional longer human-readable summary
+├── skills/
+│   └── <skill-name>/
+│       └── SKILL.md                 # reusable workflow
+└── rollout_summaries/
+    └── *.md                         # per-session rollup notes
+```
+
+Canonical files you should prefer, in order:
+
+1. `MEMORY.md` — the current compact memory. Read this first.
+2. `memory_summary.md` — longer-form summary if it exists.
+3. `skills/<name>/SKILL.md` — for reusable procedures relevant to the task.
+4. `rollout_summaries/*.md` — recent session notes, newest first.
+
+If none of the above exist for the resolved namespace, Remnic simply has
+nothing to contribute — move on without error.
+
+## Resolving the namespace
+
+Remnic uses **cwd-derived namespaces** by default. Apply this rule when
+choosing which namespace directory to read:
+
+1. Start from the session's working directory (the `cwd` Codex used for the
+   session you are consolidating).
+2. Walk upward looking for a project anchor: `.git`, `package.json`,
+   `pyproject.toml`, `Cargo.toml`, `go.mod`, or an explicit
+   `.remnic/namespace` file.
+3. The namespace is the basename of that anchor directory, lowercased and
+   with spaces replaced by `-`.
+4. If you cannot find an anchor, fall back to the namespace `default`.
+5. In addition to the project namespace, always also check the `shared`
+   namespace for cross-project preferences (e.g.
+   `<remnic-home>/memories/shared/MEMORY.md`). If it exists, read it.
+
+If a session explicitly mentions a different Remnic namespace (for example,
+the user says "use the `work` namespace"), prefer that explicit value over
+the cwd-derived one.
+
+## How to cite Remnic memories in your output
+
+When a piece of the consolidated memory you are writing comes from a Remnic
+file, cite it using the Codex memory citation block format so the user can
+trace the source:
+
+```
+<oai-mem-citation path="<path-relative-to-remnic-memory-base>" />
+```
+
+The path must be **relative to the Remnic memory base** (the directory named
+`memories/` under `<remnic-home>`), not absolute. Examples:
+
+- `<oai-mem-citation path="default/MEMORY.md" />`
+- `<oai-mem-citation path="my-project/skills/deploy/SKILL.md" />`
+- `<oai-mem-citation path="shared/memory_summary.md" />`
+
+Cite each distinct source once near the fact it supports. Do not invent
+citations for files you have not actually read.
+
+## Sandboxing rules (hard constraints)
+
+You are running in the Codex phase-2 consolidation sandbox. These rules are
+non-negotiable:
+
+- **No network.** Do not attempt HTTP calls, MCP connections, or anything
+  that reaches outside this machine.
+- **No `remnic` CLI invocation.** Do not shell out to `remnic`, `engram`,
+  `qmd`, or any daemon. Use filesystem reads only.
+- **No MCP tool calls.** You must not call `remnic.recall`,
+  `remnic.memory_store`, or any other MCP-backed tool. They are not
+  available in this sandbox.
+- **Local writes are allowed** only where Codex's sandbox policy already
+  permits them (typically the Codex memories output folder). Do not write
+  into the Remnic memory directory — it is read-only from your perspective.
+- **Respect missing files.** If a file does not exist, move on silently.
+  Never create placeholder Remnic files.
+
+## Failure handling
+
+- Remnic base directory missing: no-op. Remnic has nothing for this session.
+- Namespace directory missing: try the `shared` namespace, then give up.
+- Malformed file: skip it and continue.
+- Never block consolidation on a Remnic read error.
+
+## Quick recipe
+
+For a typical consolidation run:
+
+1. Resolve `<remnic-home>` from `$REMNIC_HOME` or `~/.remnic`.
+2. Resolve `<namespace>` from the session cwd using the rule above.
+3. Read `<remnic-home>/memories/<namespace>/MEMORY.md` if present.
+4. Read `<remnic-home>/memories/shared/MEMORY.md` if present.
+5. If the session produced or used a named workflow, read
+   `<remnic-home>/memories/<namespace>/skills/<name>/SKILL.md`.
+6. If you need more context, peek at the newest file under
+   `<remnic-home>/memories/<namespace>/rollout_summaries/`.
+7. Fold confirmed facts and preferences into the consolidated output and
+   cite them with `<oai-mem-citation />`.
+
+That is the whole extension. Keep it tight, cite your sources, and never
+invent Remnic content you did not read.

package/memories_extensions/remnic/resources/namespace-cheatsheet.md

@@ -0,0 +1,48 @@
+# Remnic Namespace Cheatsheet
+
+Remnic partitions memories into **namespaces** so multiple projects and
+contexts can share a single Remnic home without bleeding into each other.
+When the Codex consolidation sub-agent reads Remnic files, it has to pick
+the right namespace directory for the session it is summarizing. This
+cheatsheet documents the resolution rule.
+
+## Resolution rule (in order)
+
+1. **Explicit override in the session.** If the user or the transcript
+   explicitly names a Remnic namespace, use that value verbatim.
+2. **Project anchor walk.** Starting from the session's working directory,
+   walk upward until you find any of:
+   - `.git/`
+   - `.remnic/namespace` file (highest priority if present)
+   - `package.json`
+   - `pyproject.toml`
+   - `Cargo.toml`
+   - `go.mod`
+   Use the basename of the anchor directory, lowercased, with whitespace
+   replaced by `-`.
+3. **Fallback.** If nothing above matches, use the namespace `default`.
+4. **Shared overlay.** In addition to the resolved namespace, always also
+   check the `shared` namespace for cross-project content.
+
+## Examples
+
+| Session cwd                              | Anchor               | Namespace       |
+|------------------------------------------|----------------------|-----------------|
+| `/home/user/code/my-app/src`             | `/home/user/code/my-app/.git`     | `my-app`        |
+| `/home/user/code/Data Pipeline`          | `.git`               | `data-pipeline` |
+| `/tmp/scratch`                           | (none)               | `default`       |
+| `/work/research/` (contains `.remnic/namespace` = `lab`) | `.remnic/namespace` | `lab`  |
+
+## Why it matters
+
+If the consolidation agent reads from the wrong namespace, it will either
+miss relevant project-specific memories (false negative) or drag unrelated
+content into the summary (false positive). Getting the namespace right keeps
+Remnic's signal-to-noise ratio high.
+
+## What the extension does with this
+
+The consolidation sub-agent reads `MEMORY.md`, `memory_summary.md`, any
+relevant `skills/<name>/SKILL.md`, and newest `rollout_summaries/*.md`
+under the resolved namespace, plus the `shared` namespace overlay. All
+reads are filesystem-only — no CLI, no network, no MCP.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@remnic/plugin-codex",
+  "version": "1.0.0",
+  "description": "Remnic memory plugin for Codex CLI — hooks, skills, MCP integration",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joshuaswarren/remnic.git",
+    "directory": "packages/plugin-codex"
+  },
+  "keywords": [
+    "remnic",
+    "memory",
+    "codex",
+    "openai",
+    "plugin",
+    "ai-agent"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    ".codex-plugin",
+    "bin",
+    "hooks",
+    "skills",
+    "memories_extensions",
+    ".mcp.json"
+  ],
+  "dependencies": {
+    "@remnic/core": "^1.0.3"
+  }
+}

package/skills/remnic-entities/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: remnic-entities
+description: Browse entities in the Remnic knowledge graph and surface their facts and relationships. Trigger phrases include "tell me about the entity", "look up", "what do we know about".
+allowed-tools:
+  - remnic_entity_get
+---
+
+## When to use
+
+Use when the user names a specific project, person, service, or concept and asks what is known about it. Entities are the graph-shaped view of memory — structured facts and relationships rather than free text.
+
+Triggers:
+
+- "Tell me about the entity …"
+- "Look up …"
+- "What do we know about project/service/tool X?"
+- Any reference to a named thing that could have linked facts.
+
+## Inputs
+
+- `name` (required) — canonical entity name, ideally as the user wrote it.
+- Optional: entity type hint (project, person, service, tool).
+
+## Procedure
+
+1. Extract the entity name from the user's message. Preserve original capitalization unless ambiguous.
+2. Call `remnic_entity_get` with that name.
+3. If the entity is found, present its facts and relationships in a short structured view (facts, relations, last updated).
+4. If the entity is missing, say so and offer to create one via `remnic-remember` with the user's permission.
+5. When multiple candidates match, list them briefly and ask which the user meant.
+
+## Efficiency plan
+
+- Do not call `remnic_entity_get` speculatively for every proper noun — only when the user asked or the task depends on it.
+- Cache the entity payload within the current turn; do not re-fetch for the same name.
+- Pair with `remnic-recall` when unstructured context would round out the entity view.
+
+## Pitfalls and fixes
+
+- **Pitfall:** Guessing entity names. **Fix:** Use the user's wording; disambiguate rather than inventing.
+- **Pitfall:** Dumping the full entity payload. **Fix:** Summarize into a compact facts/relations/last-updated block.
+- **Pitfall:** Treating a missing entity as a bug. **Fix:** Missing just means the graph has not captured it yet — offer to create it.
+
+## Verification checklist
+
+- [ ] `remnic_entity_get` was called with a user-supplied or user-confirmed name.
+- [ ] Output shows facts, relationships, and timestamps in a compact view.
+- [ ] Missing entities are acknowledged plainly with an offer to create.
+- [ ] Legacy `engram_entity_get` alias was not preferred over `remnic_entity_get`.
+
+> Tool names: canonical name is `remnic_entity_get`. The legacy `engram_entity_get` alias remains accepted during v1.x.

package/skills/remnic-memory-workflow/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: remnic-memory-workflow
+description: Shared memory workflow for Remnic-connected agents — recall before acting, observe during work, remember at the end. Trigger phrases include "what do you remember about", "save this for later", "any context from last time".
+disable-model-invocation: true
+allowed-tools:
+  - remnic_recall
+  - remnic_memory_store
+  - remnic_lcm_search
+  - remnic_entity_get
+  - remnic_observe
+---
+
+## When to use
+
+Use this skill as the default playbook whenever an agent picks up a task that could benefit from prior context, or when the user explicitly asks the agent to remember or recall something. It is the umbrella workflow — individual skills (`remnic-recall`, `remnic-remember`, `remnic-search`, `remnic-entities`, `remnic-status`) implement the detailed steps.
+
+Triggers:
+
+- The user opens a new task, ticket, or branch.
+- The user says "what do you know about X", "have we talked about Y before", "remind me of Z".
+- The user asks the agent to save a preference, decision, or fact.
+- A long-running turn produces a durable outcome worth capturing.
+
+## Inputs
+
+- Current user request (natural language).
+- Optional: active project path, ticket number, branch name.
+- Optional: topic keywords surfaced earlier in the session.
+
+## Procedure
+
+1. **Recall first.** Call `remnic_recall` with a concise natural-language query derived from the user's request. Pull 3–8 results. Skim them for anything relevant.
+2. **Mention relevant memories briefly** to the user if they materially change the plan, otherwise quietly use them as context.
+3. **Observe during work.** For significant tool outputs (file edits, command exits, test results) call `remnic_observe` so Remnic can keep its ambient context fresh.
+4. **Deep search when needed.** If `remnic_recall` misses something the user insists exists, call `remnic_lcm_search` with a more literal phrase.
+5. **Browse entities.** When the user references a specific project, person, or concept by name, call `remnic_entity_get` to pull its facts and relationships.
+6. **Remember at the end.** Before ending the turn, store any durable decision, preference, or finding with `remnic_memory_store`. Keep each entry under ~300 tokens.
+
+## Efficiency plan
+
+- Batch recalls. One broad query is usually cheaper than several narrow ones.
+- Skip recall for trivially local requests (e.g., "format this JSON").
+- Reuse the current turn's recall results instead of re-querying within the same turn.
+- Store each memory once. If you are about to store something you just recalled, update instead of duplicating.
+
+## Pitfalls and fixes
+
+- **Pitfall:** Storing transient task state ("user is running tests now"). **Fix:** Only store facts with durable value — decisions, preferences, conclusions, long-lived context.
+- **Pitfall:** Leaking secrets into memories. **Fix:** Redact API keys, tokens, and credentials before calling `remnic_memory_store`.
+- **Pitfall:** Drowning the user in recalled context. **Fix:** Summarize in 1–3 bullet points; offer to expand on request.
+- **Pitfall:** Forgetting the write. **Fix:** Make "remember the decision" the last step of any non-trivial turn.
+
+## Verification checklist
+
+- [ ] Recall was attempted before the agent committed to a plan.
+- [ ] Any user-facing mention of recalled context was concise and attributed.
+- [ ] Durable decisions, preferences, and findings were stored via `remnic_memory_store`.
+- [ ] No secrets, credentials, or transient state were written.
+- [ ] Legacy `engram_*` aliases were NOT preferred over canonical `remnic_*` tool names.
+
+> Tool names: this skill uses the canonical `remnic_*` MCP tools. Legacy `engram_*` aliases (`engram_recall`, `engram_memory_store`, `engram_lcm_search`, `engram_entity_get`, `engram_observe`) remain accepted during v1.x for backward compatibility.