Skip to content
Back to search

remnic

Open-source memory and context for user-aware agents: scoped memory, provenance, retrieval quality, correction, boundaries, evals, and MCP/HTTP access.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/joshuaswarren/remnic with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/joshuaswarren/remnic'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/joshuaswarren--remnic/badge.svg)](/listings/joshuaswarren--remnic)

HTML

<a href="/listings/joshuaswarren--remnic"><img src="/api/listings/joshuaswarren--remnic/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The fastest judge path uses the committed synthetic mission and requires no dependency install, model call, account, or credential:

git clone https://github.com/joshuaswarren/remnic.git
cd remnic
node scripts/relay/judge-package.mjs serve

Open the printed loopback URL, compare the current and stale beliefs, open the X-Ray, review and approve the proposed correction, and follow the fresh agent through the passing payment test. Verify the same evidence from the terminal:

node scripts/relay/judge-package.mjs verify
node scripts/verify-relay-judge-package.mjs

- **Judge package:** Linux with procfs and Node.js 22.12 or newer; Linux x64 is independently clean-room verified. - **Mission Control:** Chrome/Chromium 151 verified at desktop and mobile sizes, including keyboard-only and reduced-motion flows. - **Live isolated mission runner:** Linux x64 with Codex CLI 0.144.4 or newer and the repository development dependencies. This is not required for the judge experience. - **macOS and Windows:** use the submission video/gallery or run the verifier in a supported Linux environment. The executable verifier fails closed where equivalent filesystem-safety primitives are unavailable.

Remnic's core memory engine, integrations, and benchmark framework predate Build Week. The [submission ledger](HACKATHON.md) separates that foundation from the new Relay work. See the [judge guide](docs/remnic-relay/JUDGE-GUIDE.md) and [claim ledger](docs/remnic-relay/CLAIMS.md) for the complete evidence.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 20 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "remnic",
  3. "owner": {
  4. "name": "Remnic"
  5. },
  6. "metadata": {
  7. "description": "Remnic — local-first AI memory for Claude Code: automatic recall, observation, and cross-agent knowledge sharing.",
  8. "version": "1.0.0"
  9. },
  10. "plugins": [
  11. {
  12. "name": "remnic",
  13. "source": "./packages/plugin-claude-code",
  14. "description": "Persistent long-term memory for Claude Code — wires SessionStart/UserPromptSubmit/PostToolUse hooks, MCP tools, memory skills, and the memory-review agent into a running Remnic daemon.",
  15. "homepage": "https://github.com/joshuaswarren/remnic",
  16. "category": "productivity",
  17. "keywords": ["memory", "recall", "observe", "mcp", "engram", "remnic"]
  18. }
  19. ]
  20. }
README.md · README · 580 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Remnic
  2. [![npm version](https://img.shields.io/npm/v/@remnic/cli)](https://www.npmjs.com/package/@remnic/cli)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  4. [![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink)](https://github.com/sponsors/joshuaswarren)
  5. Open-source, local-first memory and context for AI agents. One memory store, every agent.
  6. Website: **[remnic.ai](https://remnic.ai)** - guide library, comparisons, benchmarks, and changelog.
  7. ## The projects
  8. Part of the Omarchy on Apple Silicon ecosystem:
  9. - [omarchy-mlx](https://github.com/joshuaswarren/omarchy-mlx) — MLX on the Apple GPU under Linux, and Core ML models on the Neural Engine.
  10. - [omarchy-ane](https://github.com/joshuaswarren/omarchy-ane) — Linux driver for the Apple Neural Engine: DRM kernel modules and libane.
  11. - [mil-hwx-compiler](https://github.com/joshuaswarren/mil-hwx-compiler) — compiles Core ML MIL into ANE programs on Linux (M1/M2 targets).
  12. - [metal2vk](https://github.com/joshuaswarren/metal2vk) — translates Metal compute kernels to Vulkan SPIR-V with open tools.
  13. - [mesa-1](https://github.com/joshuaswarren/mesa-1) — Mesa fork carrying the Honeykrisp Vulkan driver work for Apple silicon.
  14. - [omarchy-cluster](https://github.com/joshuaswarren/omarchy-cluster) — one local model split across Macs on macOS and Omarchy Linux.
  15. - [omarchy-apple-dev](https://github.com/joshuaswarren/omarchy-apple-dev) — build and ship iOS apps from Omarchy Linux, no Xcode or Mac.
  16. - [omarchy-egpu](https://github.com/joshuaswarren/omarchy-egpu) — eGPU setup, diagnostics and measured local-inference results on Omarchy Linux.
  17. - [ane-linux-experiments](https://github.com/joshuaswarren/ane-linux-experiments) — Neural Engine on Linux: verified primitives, receipt-backed macOS parity.
  18. - [coreglass](https://github.com/joshuaswarren/coreglass) — profiler that shows where local inference loses speed on Apple Silicon Linux.
  19. - [omarchy-inference-fleet](https://github.com/joshuaswarren/omarchy-inference-fleet) — reproducible, pinned single-node MLX inference baselines.
  20. - Platform upstream: [omarchy-mac](https://github.com/omacom/omarchy-mac) — Omarchy on Apple Silicon Macs.
  21. <!-- end The projects -->
  22. - **Your files, your machine.** Memory records are plain markdown files with YAML frontmatter on your disk. Remnic also keeps local JSON and SQLite state; it does not require an external database service. `cat`, `grep`, edit, and version-control your memory files with the tools you already use.
  23. - **One memory across every tool.** OpenClaw, Claude Code, Codex CLI, Cursor, ChatGPT (developer mode), Hermes, Replit, Pi, omp, Factory Droid, and any MCP client read and write the same store. Tell one agent a preference; every agent knows it.
  24. - **Automatic extraction and recall.** Remnic watches conversations, distills durable knowledge, and injects the right context back when it is needed.
  25. - **Sharp retrieval.** Hybrid search (BM25 + vector + reranking) over rebuildable indexes, with graph recall, memory-worth scoring, and per-result provenance you can inspect.
  26. - **MIT licensed.** Free, open, and built to be forked.
  27. <!-- BEGIN BUILD FOR GOOD 2026 HIGHLIGHT -->
  28. ## Build for Good 2026: What Helps Me
  29. **Explain what helps once. Share only what you choose. Stop sharing at any time.**
  30. What Helps Me is a private support passport built on Remnic. It turns selected
  31. memories into short first-person cards. The owner reviews every word before a
  32. helper can see it.
  33. No OpenAI API key is required. Manual cards need no model. Draft and question
  34. calls use the owner's existing Remnic route, including an OpenClaw gateway or a
  35. local model.
  36. [Watch the narrated 102-second product story](docs/hackathons/assets/what-helps-me/demo.webm)
  37. or read the [full Build for Good entry](docs/hackathons/build-for-good-2026.md).
  38. The walkthrough always shows a **Synthetic replay** banner. It is not live-call
  39. proof. The separate live runner exercises the real standalone server and model
  40. flow. Its receipt validator checks internal consistency, not independent proof.
  41. ### What we built
  42. - An owner workspace for selecting exact memories, drafting cards, editing each
  43. draft, and approving each card.
  44. - Exact-version share links that last from five minutes through seven days.
  45. - A helper view that shows approved cards only and cites the card behind each
  46. grounded answer.
  47. - Immediate **Stop sharing** controls. Every helper request checks durable grant
  48. state again.
  49. - A provider-neutral model path. It uses Remnic's existing OpenClaw gateway,
  50. local, compatible remote, and optional direct OpenAI routes.
  51. - A strict live run record for draft, approval, sharing, question, revocation,
  52. and the final locked read. It stores no private text, secrets, or raw model IDs.
  53. The framing comes from [NHS England's health and care passport guidance](https://www.england.nhs.uk/long-read/health-and-care-passports-implementation-guidance/).
  54. The NHS guidance says the person owns the passport, chooses its contents, and
  55. chooses who sees it. What Helps Me applies those rules to a broader
  56. self-advocacy tool. It is not a medical record, care plan, IEP, diagnosis tool,
  57. or emergency guide.
  58. ### Who it helps
  59. What Helps Me is for people who often need to explain how others can support
  60. them. It also helps trusted helpers act on clear, current guidance without
  61. seeing the person's full memory store.
  62. ### How it will be used
  63. 1. The owner selects one to 20 notes.
  64. 2. The owner checks a clear consent box or writes a card by hand.
  65. 3. The configured model drafts up to eight cards.
  66. 4. The owner edits and approves each card.
  67. 5. The owner shares exact card versions for a set time.
  68. 6. The helper reads the guide or asks a grounded question.
  69. 7. The owner selects **Stop sharing** to lock the link.
  70. The model is the scribe. The person is the author.
  71. ### How Codex helped
  72. Codex traced Remnic's existing memory, model, HTTP, MCP, and browser contracts.
  73. It then built the feature as a seven-layer PR stack. Codex also wrote adversarial
  74. tests, checked WCAG states at four widths, and built the privacy-safe live run
  75. record. The owner approval and revocation rules remain deterministic core
  76. code. A model cannot bypass them.
  77. ### How to run the project
  78. Run the no-key synthetic walkthrough in about five minutes:
  79. ```bash
  80. git clone https://github.com/joshuaswarren/remnic.git
  81. cd remnic
  82. pnpm install --frozen-lockfile
  83. pnpm exec playwright install chromium
  84. npm run demo:support-passport:replay
  85. ```
  86. Open the printed loopback URL. The replay uses synthetic data and labels itself
  87. on every screen.
  88. Run the standalone live flow with a local, direct, or compatible model route:
  89. ```bash
  90. npm run demo:support-passport:live -- \
  91. --config ./remnic.config.json \
  92. --output ./tmp/support-passport-demo
  93. npm run demo:support-passport:validate-receipt -- \
  94. --receipt ./tmp/support-passport-demo/receipt.json
  95. ```
  96. The validator checks the self-reported receipt schema and hash consistency. It
  97. does not convert that receipt into independent attestation.
  98. For an existing OpenClaw install, keep the current gateway providers and model
  99. auth. Enable the feature, owner HTTP bridge, and gateway route in
  100. `openclaw.json`:
  101. ```jsonc
  102. {
  103. "plugins": {
  104. "entries": {
  105. "openclaw-remnic": {
  106. "config": {
  107. "modelSource": "gateway",
  108. "openaiApiKey": false,
  109. "supportPassport": { "enabled": true },
  110. "agentAccessHttp": {
  111. "enabled": true,
  112. "host": "127.0.0.1",
  113. "port": 4318,
  114. "authToken": "${OPENCLAW_REMNIC_ACCESS_TOKEN}",
  115. "principal": "passport-owner"
  116. }
  117. }
  118. }
  119. }
  120. }
  121. }
  122. ```
  123. Set `OPENCLAW_REMNIC_ACCESS_TOKEN` to a private local bearer token. This token
  124. protects the browser bridge. It is not a model provider key. Open
  125. `/remnic/ui/what-helps-me/` on the configured Remnic HTTP origin. Remnic uses
  126. the OpenClaw gateway model chain and its existing provider auth.
  127. The standalone live runner does not boot an OpenClaw host. Use the real browser
  128. flow above to exercise an existing OpenClaw gateway setup. No OpenAI API key is
  129. required. Manual cards and sharing need no model. Draft and question requests
  130. return `503 provider_unavailable` when no model route is configured.
  131. <!-- END BUILD FOR GOOD 2026 HIGHLIGHT -->
  132. <!-- BEGIN OPENAI BUILD WEEK 2026 HIGHLIGHT — temporary submission section -->
  133. ## OpenAI Build Week 2026: Remnic Relay
  134. **Correct once. Every agent learns.**
  135. Remnic is shared memory for AI agents. **Remnic Relay** is the human-governed
  136. correction loop we built for OpenAI Build Week: it exposes the stale belief
  137. behind an agent failure, shows where that belief came from, puts the proposed
  138. replacement behind human approval, and proves a brand-new agent learned the
  139. approved correction from Remnic.
  140. The demonstration follows an online-payment failure. One Codex agent reads the
  141. current rule while another confidently applies an older retry rule. Relay opens
  142. an evidence X-Ray connecting the recalled memory to the failing test, presents
  143. a before-and-after memory diff for approval, preserves the old belief as
  144. superseded, and then starts a fresh agent with no handoff. The mission is only
  145. complete when that agent recalls the replacement and turns the same payment
  146. test green.
  147. ### What we built during Build Week
  148. - a versioned contract for conflicts, evidence, corrections, lineage, and
  149. fresh-agent verification;
  150. - a human-gated correction engine with append-only supersession;
  151. - Mission Control views for conflict inspection, evidence X-Ray, approval,
  152. propagation, and the final mission receipt;
  153. - an isolated four-role Codex mission runner using only a cleared synthetic
  154. Remnic instance; and
  155. - a dependency-free judge package that binds the recorded agent run, product
  156. UI, synthetic fixture, and verification receipt into one reproducible story.
  157. ### How Codex and GPT-5.6 were used
  158. Codex collaborated across the new extension: contract modeling, correction
  159. engine, Mission Control, isolated runner, adversarial tests, evidence sealing,
  160. and judge packaging. GPT-5.6 also powers the demonstrated product workflow
  161. itself through four isolated Codex roles: Scout reads the accepted rule, a
  162. Builder acts on stale memory, a correction agent proposes the replacement, and
  163. a fresh Builder proves the approved memory propagated without an agent
  164. handoff. Agents propose; a human approves; the test proves the result.
  165. ### Install, supported platforms, and testing
  166. The fastest judge path uses the committed synthetic mission and requires no
  167. dependency install, model call, account, or credential:
  168. ```bash
  169. git clone https://github.com/joshuaswarren/remnic.git
  170. cd remnic
  171. node scripts/relay/judge-package.mjs serve
  172. ```
  173. Open the printed loopback URL, compare the current and stale beliefs, open the
  174. X-Ray, review and approve the proposed correction, and follow the fresh agent
  175. through the passing payment test. Verify the same evidence from the terminal:
  176. ```bash
  177. node scripts/relay/judge-package.mjs verify
  178. node scripts/verify-relay-judge-package.mjs
  179. ```
  180. - **Judge package:** Linux with procfs and Node.js 22.12 or newer; Linux x64 is
  181. independently clean-room verified.
  182. - **Mission Control:** Chrome/Chromium 151 verified at desktop and mobile
  183. sizes, including keyboard-only and reduced-motion flows.
  184. - **Live isolated mission runner:** Linux x64 with Codex CLI 0.144.4 or newer
  185. and the repository development dependencies. This is not required for the
  186. judge experience.
  187. - **macOS and Windows:** use the submission video/gallery or run the verifier
  188. in a supported Linux environment. The executable verifier fails closed where
  189. equivalent filesystem-safety primitives are unavailable.
  190. Remnic's core memory engine, integrations, and benchmark framework predate
  191. Build Week. The [submission ledger](HACKATHON.md) separates that foundation
  192. from the new Relay work. See the [judge guide](docs/remnic-relay/JUDGE-GUIDE.md)
  193. and [claim ledger](docs/remnic-relay/CLAIMS.md) for the complete evidence.
  194. <!-- END OPENAI BUILD WEEK 2026 HIGHLIGHT -->
  195. ## Why Remnic
  196. Most agents do not fail because they lack another prompt. They fail because they do not understand the user, the project, the boundaries, or what "good" means in context. Every session starts from zero: the agent forgets your name, your projects, the decisions you already made, and the bugs you already debugged. You re-explain the same context over and over, and the agent still repeats the same mistakes.
  197. There is a useful split in AI memory between **memory backends** (extract facts, store vectors, retrieve relevant ones) and **context substrates** (human-readable context that accumulates and compounds across sessions). Most tools pick one camp. Remnic does both:
  198. - **The files are the source of truth.** The hybrid search index is downstream of your markdown, fully rebuildable from disk, never authoritative itself.
  199. - **Recall stays sharp.** Three retrieval tiers, opt-in graph traversal, memory-worth scoring that filters low-value facts before they reach the model, and temporal supersession that keeps stale facts out.
  200. - **It compounds.** Background consolidation merges duplicates, promotes recurring themes, and snapshots page versions on every overwrite. The longer you use it, the better it gets, and you can always read exactly what it knows.
  201. | Without Remnic | With Remnic |
  202. |---|---|
  203. | Re-explain who you are and what you are working on | The agent recalls your identity, projects, and preferences automatically |
  204. | Repeat context for every task | Entity knowledge surfaces people, projects, tools, and relationships on demand |
  205. | Lose debugging and research context between sessions | Past root causes, dead ends, and findings are recalled, so work is not repeated |
  206. | Manually restate preferences every session | Preferences persist across sessions, agents, and projects |
  207. | A context-switching tax when you resume work | Session-start recall brings you back up to speed |
  208. | Built-in agent memory that does not scale | Hybrid search, lifecycle management, namespaces, and governance |
  209. | Third-party memory services that cost money and hold your data | Local memory files, with model and integration routes you control |
  210. ## How Remnic compares
  211. Most alternatives trade away at least one of local-first storage, a free license, or multi-host support; Remnic combines all three in one package.
  212. | Option | Hosting | Price | Agent coverage | Storage |
  213. |---|---|---|---|---|
  214. | Remnic | Local-first | Free (MIT) | Native plugins for Claude Code, Codex CLI, Pi, OpenClaw, Hermes, plus any MCP client | Markdown + YAML, rebuildable index |
  215. | mem0 | Cloud / self-host | Freemium | SDK / API | Vectors / database |
  216. | Letta (MemGPT) | Cloud / self-host | Freemium | API | Database-backed |
  217. | Zep (Graphiti) | Cloud / self-host | Freemium | SDK / API | Graph database |
  218. | Supermemory | Cloud | Paid | API | Hosting handled by the service |
  219. | MemPalace | Local | Free | Single host | Local |
  220. | ChatGPT memory | Cloud | Bundled | Single tool | Opaque |
  221. Hosting and price labels mirror the canonical matrix at [remnic.ai/compare](https://remnic.ai/compare), which also carries the per-competitor teardowns. Importers for mem0, Supermemory, ChatGPT, Claude, and Gemini: [remnic.ai/import](https://remnic.ai/import).
  222. ## Quick start
  223. ### Prerequisites
  224. - [Node.js](https://nodejs.org/) 22.12 or newer.
  225. - A model provider for extraction (an OpenAI API key, the OpenClaw gateway model chain, or a [local LLM](docs/guides/local-llm.md)). Retrieval-only mode needs none of these.
  226. - Optional but recommended: [QMD](https://github.com/tobi/qmd) for the highest-quality hybrid search. Without it, Remnic falls back to embedding search and then recency-ordered reads.
  227. ### Any agent (standalone)
  228. Install the CLI, start the daemon, and verify it is running.
  229. ```bash
  230. npm install -g @remnic/cli # installs `remnic` (plus the legacy `engram` forwarder)
  231. remnic init # write remnic.config.json
  232. export OPENAI_API_KEY=sk-... # extraction provider (or route to a local LLM)
  233. export REMNIC_AUTH_TOKEN=$(openssl rand -hex 32)
  234. remnic daemon start # start the background server
  235. remnic status # confirm it is running
  236. remnic query "hello" --explain # test a query with the tier breakdown
  237. ```
  238. `remnic query --explain` prints which retrieval tier produced each result and why, so you can watch the memory pipeline work on your very first query. Run `remnic doctor` any time to check your setup, then connect a tool from the table below. Full five-minute walkthrough: [docs/guides/quickstart.md](docs/guides/quickstart.md).
  239. ### OpenClaw (native plugin)
  240. OpenClaw gets the deepest integration: a memory-slot plugin that recalls every session and observes every response.
  241. ```bash
  242. openclaw plugins install clawhub:@remnic/plugin-openclaw # install the plugin
  243. remnic openclaw install # wire the memory slot in openclaw.json
  244. launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway # restart the OpenClaw gateway (macOS)
  245. remnic doctor # verify every check passes
  246. ```
  247. `remnic openclaw install` writes `plugins.entries["openclaw-remnic"]` and sets `plugins.slots.memory = "openclaw-remnic"` in `~/.openclaw/openclaw.json`. Without the slot, OpenClaw skips plugin registration and no hooks fire, so `remnic doctor` checks the slot explicitly and points you at the fix. After the restart, confirm the plugin is live:
  248. ```bash
  249. grep "gateway_start fired" ~/.openclaw/logs/gateway.log
  250. ```
  251. A matching line means Remnic is active and hooks are firing. (The `[engram]` log prefix remains during the v1.x compatibility window.)
  252. Prefer to let the agent do it? Tell any OpenClaw agent: *"Install the @remnic/plugin-openclaw plugin and configure it as my memory system."* It runs the install, updates `openclaw.json`, and restarts the gateway for you. Comprehensive install and first-run guide, including QMD setup: [docs/getting-started.md](docs/getting-started.md).
  253. ## Works with your tools
  254. One store, many front doors. Each integration reads and writes the same memory on your machine, so a preference you state in one tool is available in all of them.
  255. | Tool | Integration | Recall / observe | Docs |
  256. |------|-------------|------------------|------|
  257. | OpenClaw | Native memory-slot plugin | Every session / every response | [docs/plugins/openclaw.md](docs/plugins/openclaw.md) |
  258. | Claude Code | Native hooks + MCP | Every prompt / every tool use | [docs/plugins/claude-code.md](docs/plugins/claude-code.md) |
  259. | Codex CLI | Native hooks + MCP + memory extension | Every prompt / every tool use | [docs/plugins/codex.md](docs/plugins/codex.md) |
  260. | ChatGPT (developer mode) | MCP + OAuth 2.1 on your own server | On demand | [docs/integration/chatgpt.md](docs/integration/chatgpt.md) |
  261. | Cursor | Generic MCP client | On demand | [docs/integration/connector-setup.md](docs/integration/connector-setup.md) |
  262. | Hermes | Python `MemoryProvider` | Every LLM call / every turn | [docs/plugins/hermes.md](docs/plugins/hermes.md) |
  263. | Replit | MCP | On demand | [docs/plugins/replit.md](docs/plugins/replit.md) |
  264. | Pi Coding Agent | Native extension + MCP + compaction | Every turn / every turn | [docs/integration/pi.md](docs/integration/pi.md) |
  265. | Oh My Pi (omp) | Native extension + MCP | Every turn / every turn | [docs/integration/omp.md](docs/integration/omp.md) |
  266. | Factory Droid | HTTP MCP + bearer auth | On demand | [docs/integration/droid.md](docs/integration/droid.md) |
  267. | Any MCP client | HTTP or stdio MCP | On demand | [docs/integration/connector-setup.md](docs/integration/connector-setup.md) |
  268. Once the daemon is running, register each tool with a single command:
  269. ```bash
  270. remnic connectors install codex-cli # token + connector state + memory extension
  271. remnic connectors install claude-code # token + connector state
  272. remnic connectors install pi # token + connector state
  273. remnic connectors install omp # token + connector state
  274. remnic connectors install replit # token + connector state
  275. remnic connectors install droid # token + connector state + ~/.factory/mcp.json
  276. ```
  277. Each install mints a host-specific auth token and records Remnic-side connector state; for some hosts (such as Codex CLI) it also materializes the memory extension. How much of the host itself gets configured varies — Claude Code and Hermes, for example, need a few manual wiring steps documented in their plugin guides. See the [connector setup guide](docs/integration/connector-setup.md) for every tool, exactly what its install automates, its config snippet, and multi-tenant setups.
  278. Over MCP, Remnic exposes a rich tool surface beyond store and recall: entity lookup, memory correction, temporal recall, X-ray provenance, daily briefing, work-board, and continuity tools among them. Hosted clients call these directly, and the standalone HTTP endpoint (`remnic daemon start` or `@remnic/server`) serves the same tools. See the [HTTP + MCP API reference](docs/api.md).
  279. ## How it works
  280. Remnic runs a continuous three-phase loop around every agent conversation:
  281. ```
  282. Recall -> Before a conversation, inject the relevant memories into context
  283. Buffer -> After each turn, accumulate content until a trigger fires
  284. Extract -> Periodically, distill structured memories with an LLM and write them to disk
  285. ```
  286. - **Recall** ranks your stored memories against the incoming context and injects a budgeted slice back into the prompt. Extraction and rerank can run through the OpenClaw gateway model chain, OpenAI (Responses API), or a local LLM. See [docs/guides/cost-control.md](docs/guides/cost-control.md).
  287. - **Buffer** accumulates conversation turns until a size or time trigger fires, so extraction runs on meaningful spans rather than on every message.
  288. - **Extract** distills durable knowledge, runs it through an importance judge, and writes accepted memories to disk. The search index is then rebuilt from those files.
  289. ```mermaid
  290. flowchart LR
  291. A[Agent session] -->|recall| B[Memory store<br/>markdown + YAML]
  292. A -->|buffer turns| C[Extraction]
  293. C -->|write memories| B
  294. B -->|index| D[Hybrid search<br/>BM25 + vector + rerank]
  295. D -->|rank + explain| A
  296. ```
  297. Each memory is a portable markdown file with YAML frontmatter, so it stays git-friendly and readable with no database required:
  298. ```yaml
  299. ---
  300. id: decision-1738789200000-a1b2
  301. category: decision
  302. confidence: 0.92
  303. tags: ["architecture", "search"]
  304. ---
  305. Use the port/adapter pattern for search backends so alternative engines
  306. can replace the default index without changing core logic.
  307. ```
  308. Categories include `fact`, `decision`, `preference`, `correction`, `relationship`, `principle`, `commitment`, `skill`, and `rule`. Files are organized on disk under your configured memory directory:
  309. ```
  310. <memoryDir>/
  311. facts/ extracted facts, decisions, preferences, corrections, ...
  312. entities/ people, projects, tools, and their relationships
  313. profile.md the accumulated user profile
  314. ```
  315. The search index lives separately and is rebuildable from these files at any time. The full storage model and retrieval flow are in [docs/architecture/overview.md](docs/architecture/overview.md).
  316. ## Feature highlights
  317. **Core memory.** LLM extraction that separates durable knowledge from conversational noise, entity tracking for people, projects, tools, and relationships, a full write/consolidate/expire lifecycle, and importance gating that drops low-value facts before they are ever stored. See [docs/architecture/memory-lifecycle.md](docs/architecture/memory-lifecycle.md).
  318. **Search.** Six pluggable backends behind one interface: QMD, [Orama](https://oramasearch.com/), LanceDB, Meilisearch, a remote adapter, and a no-op. QMD is the default and highest-quality option, combining BM25, vector, and reranking. Any backend is rebuildable from your markdown at any time. See [docs/search-backends.md](docs/search-backends.md).
  319. **Memory OS.** [Namespaces](docs/namespaces.md) for multi-agent and multi-tenant isolation (opt-in via `namespacesEnabled`, default `false`), hot/cold [tiering](docs/retention-policy.md) driven by a value-score model, background consolidation via the ["dreams" surface](docs/dreams.md), opt-in [graph reasoning](docs/architecture/graph-reasoning.md) with Personalized PageRank, and transparent AES-256-GCM [at-rest encryption](docs/encryption.md) (opt-in via `secureStoreEnabled`, default `false`).
  320. **Lossless Context Management.** Archive full session transcripts and recall them losslessly through the daemon recall envelope, for when a summary is not enough. Opt-in via `lcmEnabled`, default `false`. See [docs/guides/lossless-context-management.md](docs/guides/lossless-context-management.md).
  321. **Trust and boundaries.** Scoped memory, provenance on every fact, correction handling, and boundary principles that decide when an agent should ask instead of act. See [docs/user-aware-agents.md](docs/user-aware-agents.md).
  322. **Import your memory.** Seven optional importers pull existing memory from the tools you already use. The base CLI never bundles them; install only what you need, and every run supports `--dry-run` for a zero-write preview.
  323. | Source | Package | Adapter |
  324. |--------|---------|---------|
  325. | ChatGPT | `@remnic/import-chatgpt` | `remnic import --adapter chatgpt` |
  326. | Claude | `@remnic/import-claude` | `remnic import --adapter claude` |
  327. | Gemini | `@remnic/import-gemini` | `remnic import --adapter gemini` |
  328. | mem0 | `@remnic/import-mem0` | `remnic import --adapter mem0` |
  329. | Supermemory | `@remnic/import-supermemory` | `remnic import --adapter supermemory` |
  330. | WeClone | `@remnic/import-weclone` | `openclaw engram bulk-import --source weclone` |
  331. | lossless-claw | `@remnic/import-lossless-claw` | `remnic import-lossless-claw` |
  332. See [docs/importers.md](docs/importers.md) for input formats, provenance metadata, and the full privacy breakdown.
  333. **Open Knowledge Format (OKF).** The memory directory doubles as an OKF v0.1 knowledge bundle: every memory file ships an inert `type` field next to Remnic's canonical `category`, so OKF-aware consumers can read your store without a converter. `category` stays authoritative — `type` is interop metadata and never overrides it on parse. These commands inspect, repair, and export the bundle:
  334. | Command | What it does |
  335. |---------|--------------|
  336. | `remnic okf lint` | Report files missing frontmatter or `type`; exit 1 when findings remain (`--json` for machine output) |
  337. | `remnic okf sweep` | Backfill missing `type` values from `category` without bumping `updated` (opt-in via `okf.sweepEnabled`) |
  338. | `remnic export okf --out <dir>` | Export a portable OKF v0.1 knowledge bundle (plaintext interchange; not a capsule) |
  339. Config gates, lint finding codes, and the full category-to-type mapping: [docs/okf.md](docs/okf.md).
  340. **Live connectors: Google Drive and Notion.** Beyond one-time imports, Remnic can *continuously* sync external sources into memory. The Google Drive and Notion connectors poll for changed documents on a schedule and ingest them incrementally — connect once (`remnic connectors run google-drive` / `remnic connectors run notion` for a manual sync, `remnic connectors status` to inspect), and your docs stay searchable alongside everything else your agents know. Gmail and GitHub connectors run on the hosted scheduler as well. Setup, OAuth, and polling details: [docs/live-connectors.md](docs/live-connectors.md).
  341. **Wearables.** Three optional connectors ingest AI-wearable recordings, clean and speaker-label the transcripts, apply your personal corrections, store searchable per-day transcript files, and create memories under strict per-source trust gates: `@remnic/connector-limitless` (Limitless Pendant), `@remnic/connector-bee` (Bee bracelet), and `@remnic/connector-omi` (Omi necklace). See [docs/wearables.md](docs/wearables.md).
  342. **Glass-box tooling.** [Recall X-ray](docs/xray.md) shows which retrieval tier produced each result and why, the [daily briefing](docs/guides/daily-briefing.md) surfaces active entities and open commitments, and the [operator console](docs/console.md) gives live engine introspection with trace record and replay.
  343. **Benchmarks.** Memory quality is measured, not asserted. [MemCorrect](docs/benchmarks/memcorrect.md) checks whether a backend recalls the right fact, accepts a correction, and stops serving the stale one. The [full benchmark suite](docs/benchmarks.md) covers the rest, with reproducible artifacts and leaderboard safety.
  344. **More capabilities.** A few of the deeper features, each with its own guide:
  345. - [Procedural memory](docs/procedural-memory.md) — multi-step runbooks captured from your work (on by default outside the `conservative` preset).
  346. - [Temporal recall](docs/temporal-recall.md) — `valid_at` / `invalid_at` fact lifecycle and an `as_of` recall filter.
  347. - [Pattern reinforcement](docs/pattern-reinforcement.md) — cross-session pattern detection with a recall boost for reinforced primitives.
  348. - [Shared context](docs/shared-context.md) — cross-agent shared intelligence for multi-agent teams.
  349. - [Coding-agent memory](docs/coding-agent.md) — repo conventions, review behavior, and ask-before rules for coding tools.
  350. ## Privacy and your data
  351. Memory records live in your configured directory. Local-first storage does not make every model or integration local-only.
  352. - Remnic stores memories as Markdown, alongside local indexes and other state. You can inspect, back up, and version-control the files.
  353. - Model calls follow your configuration. The local LLM route is **fail-open by default**; the `local-llm-heavy` preset does not disable cloud fallback.
  354. - For local-only use, check model routing, fallback, embeddings, reranking, briefing follow-ups, search backends, and connected clients separately. The [accessibility and privacy guide](ACCESSIBILITY.md#local-only-use-and-privacy) explains the limits and current verification status.
  355. - Hosted clients process memories they receive through Remnic's tools. Connectors, remote services, and deliberate sharing add their own data flows.
  356. - **Keep user data out of git.** Paths that contain memory content (`facts/`, `entities/`, `profile.md`) should never be committed. Enable [at-rest encryption](docs/encryption.md) if the disk itself is untrusted.
  357. ## Architecture
  358. Remnic is a [pnpm](https://pnpm.io/) monorepo of **25+ published packages**. The engine is host-agnostic; every integration is a thin adapter over it, so standalone Remnic is always first-class and adapter work follows each host's upstream SDK rather than recreating host behavior inside Remnic.
  359. ```text
  360. @remnic/core
  361. (extraction, storage, search,
  362. graph, trust, consolidation)
  363. |
  364. +-------------------+-------------------+
  365. | | |
  366. @remnic/cli @remnic/server plugins
  367. (remnic bin) (HTTP + MCP) openclaw, claude-code,
  368. codex, pi, hermes
  369. |
  370. a la carte add-ons
  371. import-* (7 importers) + connector-*
  372. (3 wearable sources)
  373. ```
  374. - **Engine:** `@remnic/core` (the framework-agnostic memory engine), `@remnic/cli` (the standalone `remnic` binary), and `@remnic/server` (HTTP + MCP server).
  375. - **Plugins:** native adapters for OpenClaw, Claude Code, Codex, and Pi, plus Hermes shipped as `remnic-hermes` on PyPI.
  376. - **A la carte:** seven `@remnic/import-*` importers and three `@remnic/connector-*` wearable connectors, installed only when you need them.
  377. - **Benchmarks:** `@remnic/bench` provides the published suites and CI regression gates.
  378. The complete package map, dependency graph, and publish order are in [docs/architecture/monorepo-structure.md](docs/architecture/monorepo-structure.md).
  379. ## Configuration
  380. `remnic init` writes `./remnic.config.json` with separate `remnic` and `server` blocks.
  381. The generated file references `OPENAI_API_KEY` and `REMNIC_AUTH_TOKEN`; configure those
  382. variables or replace the provider and auth settings for your setup. Four optional
  383. `memoryOsPreset` values seed defaults before explicit settings override them:
  384. - `conservative` keeps the footprint small and disables reranking, graph features, and procedural memory.
  385. - `balanced` is a general-purpose preset, selected explicitly by `remnic init`.
  386. - `research-max` enables graph and experimental learning features, but not every optional subsystem.
  387. - `local-llm-heavy` — tuned for local-model extraction and rerank.
  388. Without `memoryOsPreset`, the parser uses individual setting defaults rather than
  389. applying `balanced`. Extraction routing (`gateway`, OpenAI, or a local LLM), recall
  390. budget, search backend, lifecycle, namespaces, and encryption are all configurable.
  391. See [docs/config-reference.md](docs/config-reference.md) for config keys, defaults,
  392. and operator guidance.
  393. ## Self-hosting and operators
  394. Running Remnic for a team or across machines? `remnic daemon start` hands off to launchd or systemd when a service is installed, and `@remnic/server` exposes the same memory over HTTP + MCP for remote agents. Namespaces isolate tenants, and the standalone server supports multi-tenant, multi-harness setups.
  395. - [Standalone server guide](docs/guides/standalone-server.md) — multi-tenant setup and connecting multiple harnesses.
  396. - [Deployment topologies](docs/integration/deployment-topologies.md) — localhost, LAN, remote, and containerized layouts.
  397. - [Operations](docs/operations.md) — backups, exports, hourly summaries, and logs.
  398. ## Documentation
  399. The complete, organized docs hub lives at **[docs/README.md](docs/README.md)**. Starting points by journey:
  400. - **Start here:** [Quickstart](docs/guides/quickstart.md) - [Getting started](docs/getting-started.md) - [CLI reference](docs/cli.md)
  401. - [Accessibility](ACCESSIBILITY.md) covers helpful features, privacy controls, testing limits, and feedback.
  402. - [How I use Remnic every day](docs/DAILY-USE.md) is a 30-day log of retained memories with recent recall timing, the command behind each number, and what is not measured.
  403. - [Community numbers](docs/COMMUNITY-NUMBERS.md) counts stars, forks, and contributors, with the source and date behind each figure.
  404. - **Connect your tools:** [Connector setup](docs/integration/connector-setup.md) - [ChatGPT](docs/integration/chatgpt.md) - [Plugins index](docs/plugins/README.md) - [Deployment topologies](docs/integration/deployment-topologies.md)
  405. - **Configure:** [Config reference](docs/config-reference.md) - [Search backends](docs/search-backends.md) - [Local LLM](docs/guides/local-llm.md) - [Cost control](docs/guides/cost-control.md)
  406. - **Operate:** [Operations](docs/operations.md) - [Retention policy](docs/retention-policy.md) - [Import / export](docs/import-export.md) - [Standalone server](docs/guides/standalone-server.md)
  407. - **Internals:** [Architecture overview](docs/architecture/overview.md) - [Retrieval pipeline](docs/architecture/retrieval-pipeline.md) - [Memory lifecycle](docs/architecture/memory-lifecycle.md) - [HTTP + MCP API](docs/api.md)
  408. The website publishes the [guide library](https://remnic.ai/guides) (what is AI agent memory, MCP memory servers, Claude Code memory), the [comparison pages](https://remnic.ai/compare), the [benchmarks report](https://remnic.ai/benchmarks), and the [changelog](https://remnic.ai/changelog).
  409. ## FAQ
  410. **Do I need OpenClaw?** No. Remnic runs standalone through `@remnic/cli` and connects to any tool over MCP or HTTP. OpenClaw simply gets the deepest native integration.
  411. **Does it work offline or without an API key?** Local file retrieval can work without a model provider. Extraction needs a model. A [local LLM](docs/guides/local-llm.md) can serve it, but fallback and other configured routes need separate checks before claiming local-only operation.
  412. **Where is my data?** Memory records live under your configured memory directory. Models, search services, hosted clients, connectors, and sharing can send data elsewhere. See [Privacy and your data](#privacy-and-your-data).
  413. **How much does it cost?** The software is MIT and free. Your only cost is your chosen extraction provider, which is zero when you use a local LLM.
  414. **Do I need QMD?** No, but it gives the best search. Without it, Remnic falls back to embedding search and then recency-ordered reads.
  415. **Can multiple agents share one memory?** Yes. Every connected tool reads and writes the same store, and [namespaces](docs/namespaces.md) isolate tenants when you want separation.
  416. **Is it production-ready?** Remnic is extensively tested with CI regression gates and a published benchmark suite. See [docs/benchmarks.md](docs/benchmarks.md) for the evidence.
  417. **I was using Engram.** Everything still works. See [Engram to Remnic](#engram-to-remnic) below for the migration path.
  418. ## Engram to Remnic
  419. Engram is now Remnic. Canonical packages live under the `@remnic/*` scope, and OpenClaw installs use [`@remnic/plugin-openclaw`](https://www.npmjs.com/package/@remnic/plugin-openclaw). The legacy `engram` CLI name, the `openclaw engram` command namespace, and the `/engram/v1/...` HTTP paths remain available as a compatibility surface during the rename window. Migrating an existing install? Run `remnic openclaw migrate-engram --yes`, which backs up the legacy extension, installs the new plugin, preserves your `memoryDir`, and switches the memory slot. Full steps: [Engram to Remnic migration guide](docs/guides/openclaw-engram-to-remnic.md).
  420. Read [Accessibility](ACCESSIBILITY.md) for useful features, privacy limits, and the local-model checks marked Measured or Not measured.
  421. - [Feature roadmap (GitHub Project)](https://github.com/users/joshuaswarren/projects/1) — current priority order, blockers, and next work.
  422. - [Issues](https://github.com/joshuaswarren/remnic/issues) — report a bug or request a feature.
  423. - [Contributing](CONTRIBUTING.md) — how to build Remnic and open a pull request.
  424. - [Contributors](CONTRIBUTORS.md) — every outside contributor and what they built.
  425. ## Support
  426. Every bit of support helps keep Remnic alive and free. If you are able, [sponsor on GitHub](https://github.com/sponsors/joshuaswarren) or send a Lightning donation to `joshuaswarren@strike.me` to directly fund continued development and new integrations.
  427. [![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?style=for-the-badge)](https://github.com/sponsors/joshuaswarren)
  428. If financial support is not an option, you can still make a big difference: [star the repo](https://github.com/joshuaswarren/remnic), share it, or recommend it to a colleague. Word of mouth is how most people find Remnic.
  429. ## Contributing
  430. Contributions from humans and AI-assisted contributors are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the preflight gate, and PR expectations. Deeper references: [docs/development/contributing.md](docs/development/contributing.md) and [docs/CONVENTIONS.md](docs/CONVENTIONS.md).
  431. ## License
  432. [MIT](LICENSE)
packages/plugin-claude-code/hooks/bin/remnic-cc-hook.test.cjs · Bundled script · 1,021 lines · 2 findings marked
  1. "use strict";
  2. // Integration tests for the unified Claude Code hook runner (issue #1518).
  3. // Each test spawns the real remnic-cc-hook.cjs against a mock Remnic HTTP
  4. // server, with an isolated HOME/XDG_STATE_HOME, and asserts both the emitted
  5. // hook JSON and the cursor/observe side effects. These tests cover the
  6. // cross-platform failure classes called out in #1518:
  7. // - shell-metacharacter session ids are rejected (no shell injection vector)
  8. // - short prompts skipped, no-token skipped, dead-daemon guidance
  9. // - cursor retention on failed final flush (no data loss)
  10. // - payload via stdin (not env) so large edits do not E2BIG on Windows
  11. // - hooks.json uses exec form (command + args) so Windows works without
  12. // Git Bash and shell metacharacters in the plugin root cannot inject
  13. const assert = require("node:assert/strict");
  14. const test = require("node:test");
  15. const http = require("node:http");
  16. const fs = require("node:fs");
  17. const os = require("node:os");
  18. const path = require("node:path");
  19. const { spawn } = require("node:child_process");
  20. const RUNNER = path.join(__dirname, "remnic-cc-hook.cjs");
  21. // Shared runner source (issue #2483): implementation-detail assertions read
  22. // the core, while behavioral tests spawn the wrapper entry (RUNNER).
  23. const CORE = path.join(__dirname, "remnic-hook-core.cjs");
  24. function startServer(handler) {
  25. const calls = [];
  26. const server = http.createServer((req, res) => {
  27. let body = "";
  28. req.on("data", (c) => (body += c));
  29. req.on("end", () => {
  30. let parsed = null;
  31. try {
  32. parsed = body ? JSON.parse(body) : null;
  33. } catch {
  34. parsed = body;
  35. }
  36. calls.push({ method: req.method, url: req.url, body: parsed });
  37. handler(req, res, parsed);
  38. });
  39. });
  40. return new Promise((resolve) => {
  41. server.listen(0, "127.0.0.1", () => {
  42. resolve({ server, port: server.address().port, calls });
  43. });
  44. });
  45. }
  46. function mkHome() {
  47. const dir = fs.mkdtempSync(path.join(os.tmpdir(), "remnic-cc-test-"));
  48. return dir;
  49. }
  50. // Async spawn (NOT spawnSync) so the in-process mock HTTP server's event loop
  51. // stays free to answer the runner's requests while it runs.
  52. function runHook(event, input, { port, home, env = {} } = {}) {
  53. return new Promise((resolve) => {
  54. const child = spawn(process.execPath, [RUNNER, event], {
  55. env: {
  56. ...process.env,
  57. HOME: home,
  58. USERPROFILE: home,
  59. XDG_STATE_HOME: path.join(home, "state"),
  60. REMNIC_HOST: "127.0.0.1",
  61. REMNIC_PORT: String(port),
  62. // Default to an env token unless a test overrides it. Every env name
  63. // resolveToken() consults is pinned here — including the canonical
  64. // REMNIC_AUTH_TOKEN / ENGRAM_AUTH_TOKEN pair — so a value inherited
  65. // from the parent shell (a developer or CI runner that authenticates
  66. // a local daemon) cannot leak through `...process.env` and make the
  67. // no-token path take a token (#1518 test isolation). Tests that want
  68. // a specific name set it through `env.extra`, which is spread last.
  69. OPENCLAW_REMNIC_ACCESS_TOKEN: env.token === null ? "" : env.token || "test-token",
  70. OPENCLAW_ENGRAM_ACCESS_TOKEN: "",
  71. REMNIC_AUTH_TOKEN: "",
  72. ENGRAM_AUTH_TOKEN: "",
  73. // Internal worker-propagation channel, not a user credential. Pinned
  74. // so an inherited value cannot reach the detached observe worker.
  75. REMNIC_HOOK_TOKEN: "",
  76. // Clear daemon URL env so a developer shell with REMNIC_DAEMON_URL
  77. // set can't route tests away from the mock server (the shared core
  78. // honors it since issue #2483). Tests that WANT a daemon URL
  79. // override it via env.extra (which spreads last).
  80. REMNIC_DAEMON_URL: "",
  81. ENGRAM_DAEMON_URL: "",
  82. ...env.extra,
  83. },
  84. stdio: ["pipe", "pipe", "pipe"],
  85. });
  86. let stdout = "";
  87. let stderr = "";
  88. child.stdout.on("data", (d) => (stdout += d));
  89. child.stderr.on("data", (d) => (stderr += d));
  90. child.on("close", () => {
  91. let json = null;
  92. try {
  93. json = JSON.parse(stdout.trim().split("\n").filter(Boolean).pop());
  94. } catch {
  95. /* leave null */
  96. }
  97. resolve({ stdout, stderr, json });
  98. });
  99. child.stdin.end(typeof input === "string" ? input : JSON.stringify(input));
  100. });
  101. }
  102. function transcript(home, messages) {
  103. const file = path.join(home, "transcript.jsonl");
  104. const lines = messages.map((m) => JSON.stringify({ type: m.role, message: { role: m.role, content: m.content } }));
  105. fs.writeFileSync(file, lines.join("\n") + "\n");
  106. return file;
  107. }
  108. function cursorPath(home, sessionId) {
  109. return path.join(home, "state", "remnic", "hooks", `remnic-cursor-${sessionId}`);
  110. }
  111. // ── session-start ──────────────────────────────────────────────────────────
  112. test("session-start: healthy server returns recall context with codingContext cleared outside a repo", async () => {
  113. const home = mkHome();
  114. const { server, port, calls } = await startServer((req, res) => {
  115. if (req.url === "/engram/v1/live") return res.writeHead(200).end("ok");
  116. if (req.url === "/engram/v1/recall") {
  117. return res.writeHead(200, { "Content-Type": "application/json" }).end(
  118. JSON.stringify({ context: "remembered preferences", count: 3, mode: "auto" }),
  119. );
  120. }
  121. res.writeHead(404).end();
  122. });
  123. try {
  124. const { json } = await runHook("session-start", { session_id: "s1", cwd: home }, { port, home });
  125. assert.equal(json.continue, true);
  126. assert.match(json.hookSpecificOutput.additionalContext, /Remnic Memory Recall — 3 memories/);
  127. assert.match(json.hookSpecificOutput.additionalContext, /remembered preferences/);
  128. const recall = calls.find((c) => c.url === "/engram/v1/recall");
  129. assert.ok(recall, "recall was called");
  130. assert.equal(recall.body.mode, "auto");
  131. assert.equal(recall.body.topK, 12);
  132. // claude-code client id header
  133. assert.equal(recall.method, "POST");
  134. // Outside a git repo, codingContext is explicitly null (clears stale routing).
  135. assert.ok("codingContext" in recall.body);
  136. assert.equal(recall.body.codingContext, null);
  137. } finally {
  138. server.close();
  139. fs.rmSync(home, { recursive: true, force: true });
  140. }
  141. });
  142. test("session-start: health probe carries the bearer token (auth-gated daemons)", async () => {
  143. const home = mkHome();
  144. let healthAuth = "unset";
  145. const { server, port } = await startServer((req, res) => {
  146. if (req.url === "/engram/v1/live") {
  147. healthAuth = req.headers.authorization || null;
  148. return res.writeHead(200).end("ok");
  149. }
  150. if (req.url === "/engram/v1/recall") {
  151. return res
  152. .writeHead(200, { "Content-Type": "application/json" })
  153. .end(JSON.stringify({ context: "ctx", count: 1, mode: "auto" }));
  154. }
  155. res.writeHead(404).end();
  156. });
  157. try {
  158. await runHook("session-start", { session_id: "s1", cwd: home }, { port, home });
  159. // Without this header an auth-gated daemon 401s the probe and the hook
  160. // reports "daemon not running", silently skipping recall/observe.
  161. assert.equal(healthAuth, "Bearer test-token");
  162. } finally {
  163. server.close();
  164. fs.rmSync(home, { recursive: true, force: true });
  165. }
  166. });
  167. test("session-start: hung diagnostic /health does not stall the live probe (#3257)", async () => {
  168. const home = mkHome();
  169. const { server, port, calls } = await startServer((req, res) => {
  170. // The expensive diagnostic route never answers; only /live is healthy.
  171. if (req.url === "/engram/v1/health") return;
  172. if (req.url === "/engram/v1/live") return res.writeHead(200).end("ok");
  173. if (req.url === "/engram/v1/recall") {
  174. return res.writeHead(200, { "Content-Type": "application/json" }).end(
  175. JSON.stringify({ context: "live recall", count: 1, mode: "auto" }),
  176. );
  177. }
  178. res.writeHead(404).end();
  179. });
  180. try {
  181. const { json } = await runHook("session-start", { session_id: "s1", cwd: home }, { port, home });
  182. assert.equal(json.continue, true);
  183. assert.match(json.hookSpecificOutput.additionalContext, /live recall/);
  184. assert.ok(calls.some((c) => c.url === "/engram/v1/recall"), "recall reached the daemon");
  185. } finally {
  186. server.close();
  187. fs.rmSync(home, { recursive: true, force: true });
  188. }
  189. });
  190. test("session-start: 404 live falls back to legacy health within one budget", async () => {
  191. const home = mkHome();
  192. const { server, port, calls } = await startServer((req, res) => {
  193. if (req.url === "/engram/v1/live") return res.writeHead(404).end();
  194. if (req.url === "/engram/v1/health") return res.writeHead(200).end("ok");
  195. if (req.url === "/engram/v1/recall") {
  196. return res.writeHead(200, { "Content-Type": "application/json" }).end(
  197. JSON.stringify({ context: "legacy recall", count: 1, mode: "auto" }),
  198. );
  199. }
  200. res.writeHead(404).end();
  201. });
  202. try {
  203. const { json } = await runHook("session-start", { session_id: "s1", cwd: home }, { port, home });
  204. assert.equal(json.continue, true);
  205. assert.match(json.hookSpecificOutput.additionalContext, /legacy recall/);
  206. const probeUrls = calls.filter((c) => c.url === "/engram/v1/live" || c.url === "/engram/v1/health").map((c) => c.url);
  207. assert.deepEqual(probeUrls, ["/engram/v1/live", "/engram/v1/health"]);
  208. } finally {
  209. server.close();
  210. fs.rmSync(home, { recursive: true, force: true });
  211. }
  212. });
  213. test("session-start: 503 live is a final answer with no legacy retry", async () => {
  214. const home = mkHome();
  215. const { server, port, calls } = await startServer((req, res) => {
  216. if (req.url === "/engram/v1/live") return res.writeHead(503).end();
  217. // A 503 must NOT be re-probed on the legacy route, even when it would pass.
  218. if (req.url === "/engram/v1/health") return res.writeHead(200).end("ok");
  219. if (req.url === "/engram/v1/recall") {
  220. return res.writeHead(200, { "Content-Type": "application/json" }).end(
  221. JSON.stringify({ context: "ctx", count: 1, mode: "auto" }),
  222. );
  223. }
  224. res.writeHead(404).end();
  225. });
  226. try {
  227. const { json } = await runHook("session-start", { session_id: "s1", cwd: home }, { port, home });
  228. assert.match(json.hookSpecificOutput.additionalContext, /daemon not running/);
  229. assert.ok(!calls.some((c) => c.url === "/engram/v1/recall"), "recall is skipped");
  230. assert.deepEqual(
  231. calls.filter((c) => c.url.startsWith("/engram/v1/")).map((c) => c.url),
  232. ["/engram/v1/live", "/engram/v1/live"],
  233. );
  234. } finally {
  235. server.close();
  236. fs.rmSync(home, { recursive: true, force: true });
  237. }
  238. });
  239. test("session-start: REMNIC_DAEMON_URL routes recall to the remote base URL (#2483)", async () => {
  240. const home = mkHome();
  241. const { server, port, calls } = await startServer((req, res) => {
  242. if (req.url === "/engram/v1/live") return res.writeHead(200).end("ok");
  243. if (req.url === "/engram/v1/recall") {
  244. return res.writeHead(200, { "Content-Type": "application/json" }).end(
  245. JSON.stringify({ context: "remote recall", count: 1, mode: "auto" }),
  246. );
  247. }
  248. res.writeHead(404).end();
  249. });
  250. try {
  251. // A full REMNIC_DAEMON_URL must take precedence over the (wrong) PORT —
  252. // the same remote/central-daemon contract the Codex runner has had since
  253. // #1571. Issue #2483: the Claude Code hook inherits it via the shared
  254. // core, so a Claude Code host can also reach a remote daemon over
  255. // Tailscale/LAN/VPN (plain or TLS).
  256. const { json } = await runHook(
  257. "session-start",
  258. { session_id: "remote-1", cwd: home },
  259. {
  260. port: 1, // deliberately unused; daemon URL wins
  261. home,
  262. env: { extra: { REMNIC_DAEMON_URL: `http://127.0.0.1:${port}` } },
  263. },
  264. );
  265. assert.equal(json.continue, true);
  266. assert.match(json.hookSpecificOutput.additionalContext, /remote recall/);
  267. assert.ok(
  268. calls.some((c) => c.url === "/engram/v1/recall"),
  269. "recall reached the REMNIC_DAEMON_URL host",
  270. );
  271. } finally {
  272. server.close();
  273. fs.rmSync(home, { recursive: true, force: true });
  274. }
  275. });
  276. test("recall body targets REMNIC_NAMESPACE when set, and omits namespace when unset", async () => {
  277. const mk = () =>
  278. startServer((req, res) => {
  279. if (req.url === "/engram/v1/live") return res.writeHead(200).end("ok");
  280. if (req.url === "/engram/v1/recall") {
  281. return res
  282. .writeHead(200, { "Content-Type": "application/json" })
  283. .end(JSON.stringify({ context: "ctx", count: 1, mode: "auto" }));
  284. }
  285. res.writeHead(404).end();
  286. });
  287. // set → namespace travels in the request body (REST reads it from the body,
  288. // not a header; the "claude-code" client id otherwise resolves to the
  289. // adapter's own empty namespace and recall returns nothing).
  290. {
  291. const home = mkHome();
  292. const { server, port, calls } = await mk();
  293. try {
  294. await runHook(
  295. "session-start",
  296. { session_id: "s1", cwd: home },
  297. { port, home, env: { extra: { REMNIC_NAMESPACE: "team-shared" } } },
  298. );
  299. const recall = calls.find((c) => c.url === "/engram/v1/recall");
  300. assert.ok(recall, "recall was called");
  301. assert.equal(recall.body.namespace, "team-shared");
  302. } finally {
  303. server.close();
  304. fs.rmSync(home, { recursive: true, force: true });
  305. }
  306. }
  307. // unset → opt-in no-op, no namespace field (behaviour unchanged for existing users).
  308. // Explicitly clear both env vars so a value inherited from the developer's
  309. // shell (`...process.env`) can't leak in and make this path look "set".
  310. {
  311. const home = mkHome();
  312. const { server, port, calls } = await mk();
  313. try {
  314. await runHook(
  315. "session-start",
  316. { session_id: "s1", cwd: home },
  317. { port, home, env: { extra: { REMNIC_NAMESPACE: "", ENGRAM_NAMESPACE: "" } } },
  318. );
  319. const recall = calls.find((c) => c.url === "/engram/v1/recall");
  320. assert.ok(recall, "recall was called");
  321. assert.equal("namespace" in recall.body, false);
  322. } finally {
  323. server.close();
  324. fs.rmSync(home, { recursive: true, force: true });
  325. }
  326. }
  327. });
  328. test("namespace targeting: ENGRAM_NAMESPACE fallback (recall) and observe body both honor it", async () => {
  329. // ENGRAM_NAMESPACE is the fallback when REMNIC_NAMESPACE is unset → recall body carries it.
  330. {
  331. const home = mkHome();
  332. const { server, port, calls } = await startServer((req, res) => {
  333. if (req.url === "/engram/v1/live") return res.writeHead(200).end("ok");
  334. if (req.url === "/engram/v1/recall") {
  335. return res
  336. .writeHead(200, { "Content-Type": "application/json" })
  337. .end(JSON.stringify({ context: "ctx", count: 1, mode: "auto" }));
  338. }
  339. res.writeHead(404).end();
  340. });
  341. try {
  342. await runHook(
  343. "session-start",
  344. { session_id: "s1", cwd: home },
  345. { port, home, env: { extra: { REMNIC_NAMESPACE: "", ENGRAM_NAMESPACE: "legacy-ns" } } },
  346. );
  347. const recall = calls.find((c) => c.url === "/engram/v1/recall");
  348. assert.ok(recall, "recall was called");
  349. assert.equal(recall.body.namespace, "legacy-ns");
  350. } finally {
  351. server.close();
  352. fs.rmSync(home, { recursive: true, force: true });
  353. }
  354. }
  355. // observe uses the same httpPost path, so its body carries the namespace too.
  356. {
  357. const home = mkHome();
  358. const { server, port, calls } = await startServer((req, res) => res.writeHead(200).end("{}"));
  359. try {
  360. const tpath = transcript(home, [
  361. { role: "user", content: "first" },
  362. { role: "assistant", content: "second" },
  363. ]);
  364. await runHook(
  365. "__observe-worker__",
  366. JSON.stringify({ session_id: "sObsNs", transcript_path: tpath }),
  367. { port, home, env: { extra: { REMNIC_NAMESPACE: "team-shared", ENGRAM_NAMESPACE: "" } } },
  368. );
  369. const observe = calls.find((c) => c.url === "/engram/v1/observe");
  370. assert.ok(observe, "observe was called");
  371. assert.equal(observe.body.namespace, "team-shared");
  372. } finally {
  373. server.close();
  374. fs.rmSync(home, { recursive: true, force: true });
  375. }
  376. }
  377. });
  378. test("session-start: falls back to minimal mode when full recall fails", async () => {
  379. const home = mkHome();
  380. let recallHits = 0;
  381. const { server, port, calls } = await startServer((req, res) => {
  382. if (req.url === "/engram/v1/live") return res.writeHead(200).end("ok");
  383. if (req.url === "/engram/v1/recall") {
  384. recallHits += 1;
  385. if (recallHits === 1) return res.writeHead(500).end("boom");
  386. return res.writeHead(200).end(JSON.stringify({ context: "fallback ctx", count: 1, mode: "minimal" }));
  387. }
  388. res.writeHead(404).end();
  389. });
  390. try {
  391. const { json } = await runHook("session-start", { session_id: "s1", cwd: home }, { port, home });
  392. assert.match(json.hookSpecificOutput.additionalContext, /minimal mode/);
  393. const recalls = calls.filter((c) => c.url === "/engram/v1/recall");
  394. assert.equal(recalls.length, 2);
  395. assert.equal(recalls[1].body.mode, "minimal");
  396. assert.equal(recalls[1].body.topK, 8);
  397. } finally {
  398. server.close();
  399. fs.rmSync(home, { recursive: true, force: true });
  400. }
  401. });
  402. test("session-start: no token → claude-code install hint, no recall call", async () => {
  403. const home = mkHome();
  404. const { server, port, calls } = await startServer((req, res) => {
  405. if (req.url === "/engram/v1/live") return res.writeHead(200).end("ok");
  406. res.writeHead(200).end("{}");
  407. });
  408. try {
  409. const { json } = await runHook("session-start", { session_id: "s1", cwd: home }, { port, home, env: { token: null } });
  410. assert.match(json.hookSpecificOutput.additionalContext, /no auth token/);
  411. assert.match(json.hookSpecificOutput.additionalContext, /claude-code/);
  412. assert.equal(calls.filter((c) => c.url === "/engram/v1/recall").length, 0);
  413. } finally {
  414. server.close();
  415. fs.rmSync(home, { recursive: true, force: true });
  416. }
  417. });
  418. test("session-start: dead daemon → distinct daemon-not-running message", async () => {
  419. const home = mkHome();
  420. // Use a port with no listener to simulate a dead daemon.
  421. const dead = await startServer(() => {});
  422. const port = dead.port;
  423. dead.server.close();
  424. await new Promise((r) => setTimeout(r, 50));
  425. const { json } = await runHook("session-start", { session_id: "s1", cwd: home }, { port, home });
  426. assert.match(json.hookSpecificOutput.additionalContext, /daemon not running/);
  427. fs.rmSync(home, { recursive: true, force: true });
  428. });
  429. // ── user-prompt-recall ─────────────────────────────────────────────────────
  430. test("user-prompt-recall: short prompt is skipped with bare continue", async () => {
  431. const home = mkHome();
  432. const { server, port, calls } = await startServer((req, res) => res.writeHead(200).end("{}"));
  433. try {
  434. const { json } = await runHook("user-prompt-recall", { session_id: "s1", prompt: "hi there" }, { port, home });
  435. assert.deepEqual(json, { continue: true });
  436. assert.equal(calls.length, 0);
  437. } finally {
  438. server.close();
  439. fs.rmSync(home, { recursive: true, force: true });
  440. }
  441. });
  442. test("user-prompt-recall: no token → bare continue, no banner, no call", async () => {
  443. const home = mkHome();
  444. const { server, port, calls } = await startServer((req, res) => res.writeHead(200).end("{}"));
  445. try {
  446. const { json } = await runHook(
  447. "user-prompt-recall",
  448. { session_id: "s1", prompt: "this is a sufficiently long prompt" },
  449. { port, home, env: { token: null } },
  450. );
  451. assert.deepEqual(json, { continue: true });
  452. assert.equal(calls.length, 0);
  453. } finally {
  454. server.close();
  455. fs.rmSync(home, { recursive: true, force: true });
  456. }
  457. });
  458. test("user-prompt-recall: long prompt injects <remnic-memory> context", async () => {
  459. const home = mkHome();
  460. const { server, port, calls } = await startServer((req, res) => {
  461. if (req.url === "/engram/v1/recall") {
  462. return res.writeHead(200).end(JSON.stringify({ context: "rel ctx", count: 2 }));
  463. }
  464. res.writeHead(404).end();
  465. });
  466. try {
  467. const { json } = await runHook(
  468. "user-prompt-recall",
  469. { session_id: "s1", prompt: "please recall the deployment decisions we made" },
  470. { port, home },
  471. );
  472. assert.match(json.hookSpecificOutput.additionalContext, /<remnic-memory count="2">/);
  473. assert.equal(calls[0].body.mode, "minimal");
  474. } finally {
  475. server.close();
  476. fs.rmSync(home, { recursive: true, force: true });
  477. }
  478. });
  479. // ── post-tool-observe ──────────────────────────────────────────────────────
  480. test("observe worker: advances cursor only after a successful observe", async () => {
  481. const home = mkHome();
  482. const { server, port, calls } = await startServer((req, res) => res.writeHead(200).end("{}"));
  483. try {
  484. const tpath = transcript(home, [
  485. { role: "user", content: "first" },
  486. { role: "assistant", content: "second" },
  487. ]);
  488. await runHook(
  489. "__observe-worker__",
  490. JSON.stringify({ session_id: "sObs", transcript_path: tpath }),
  491. { port, home },
  492. );
  493. const observe = calls.find((c) => c.url === "/engram/v1/observe");
  494. assert.ok(observe, "observe was called");
  495. assert.equal(observe.body.messages.length, 2);
  496. assert.equal(fs.readFileSync(cursorPath(home, "sObs"), "utf8").trim(), "2");
  497. } finally {
  498. server.close();
  499. fs.rmSync(home, { recursive: true, force: true });
  500. }
  501. });
  502. test("observe worker: does NOT advance the cursor when observe fails", async () => {
  503. const home = mkHome();
  504. const { server, port } = await startServer((req, res) => {
  505. if (req.url === "/engram/v1/observe") return res.writeHead(500).end("boom");
  506. res.writeHead(200).end("{}");
  507. });
  508. try {
  509. const tpath = transcript(home, [{ role: "user", content: "only" }]);
  510. await runHook(
  511. "__observe-worker__",
  512. JSON.stringify({ session_id: "sFail", transcript_path: tpath }),
  513. { port, home },
  514. );
  515. assert.equal(fs.existsSync(cursorPath(home, "sFail")), false, "cursor must not be written on failure");
  516. } finally {
  517. server.close();
  518. fs.rmSync(home, { recursive: true, force: true });
  519. }
  520. });
  521. test("observe worker: shell-metacharacter session id is rejected (no injection vector)", async () => {
  522. // A session id containing shell metacharacters must NOT reach the observe
  523. // endpoint or the cursor filesystem path. The runner validates the id
  524. // charset so a malicious payload field can never become a path traversal
  525. // or a shell argument even if a future caller regresses to shell=true.
  526. const home = mkHome();
  527. const { server, port, calls } = await startServer((req, res) => res.writeHead(200).end("{}"));
  528. try {
  529. const tpath = transcript(home, [{ role: "user", content: "x" }]);
  530. await runHook(
  531. "__observe-worker__",
  532. JSON.stringify({ session_id: "s; rm -rf /", transcript_path: tpath }),
    • Note: Quoted as data in code: Runs `rm -rf` against a root or home-directory path
    • Line 563 on GitHub
  533. { port, home },
  534. );
  535. assert.equal(calls.filter((c) => c.url === "/engram/v1/observe").length, 0, "no observe for invalid session id");
  536. assert.equal(
  537. fs.existsSync(cursorPath(home, "s; rm -rf /")),
    • Note: Quoted as data in code: Runs `rm -rf` against a root or home-directory path
    • Line 568 on GitHub
  538. false,
  539. "no cursor file written for invalid session id",
  540. );
  541. } finally {
  542. server.close();
  543. fs.rmSync(home, { recursive: true, force: true });
  544. }
  545. });
  546. test("post-tool-observe: foreground emits continue immediately", async () => {
  547. const home = mkHome();
  548. const { server, port } = await startServer((req, res) => res.writeHead(200).end("{}"));
  549. try {
  550. const tpath = transcript(home, [{ role: "user", content: "x" }]);
  551. const { json } = await runHook("post-tool-observe", { session_id: "sPt", transcript_path: tpath }, { port, home });
  552. assert.deepEqual(json, { continue: true });
  553. } finally {
  554. server.close();
  555. fs.rmSync(home, { recursive: true, force: true });
  556. }
  557. });
  558. test("post-tool-observe: worker payload travels via STDIN, not the environment", async () => {
  559. // Windows caps the environment block at ~32 KB. Large PostToolUse payloads
  560. // (big file edits) would E2BIG; the worker reads stdin instead. We assert
  561. // the source rather than running an E2BIG payload because reproducing the
  562. // limit cross-platform is impractical.
  563. const src = fs.readFileSync(CORE, "utf8");
  564. assert.doesNotMatch(
  565. src,
  566. /REMNIC_HOOK_INPUT:\s*rawInput/,
  567. "foreground hook must NOT propagate the payload via env (E2BIG on Windows)",
  568. );
  569. assert.match(
  570. src,
  571. /child\.stdin\.end\(rawInput\)/,
  572. "foreground hook must write the payload to the worker's stdin",
  573. );
  574. });
  575. test("unknown event fails open with continue", async () => {
  576. const home = mkHome();
  577. const { server, port } = await startServer((req, res) => res.writeHead(200).end("{}"));
  578. try {
  579. const { json } = await runHook("bogus-event", {}, { port, home });
  580. assert.deepEqual(json, { continue: true });
  581. } finally {
  582. server.close();
  583. fs.rmSync(home, { recursive: true, force: true });
  584. }
  585. });
  586. // ── session-end ────────────────────────────────────────────────────────────
  587. test("session-end: retains the cursor when the final flush fails (no data loss)", async () => {
  588. const home = mkHome();
  589. const { server, port } = await startServer((req, res) => {
  590. if (req.url === "/engram/v1/observe") return res.writeHead(503).end("down");
  591. res.writeHead(200).end("{}");
  592. });
  593. try {
  594. const tpath = transcript(home, [{ role: "user", content: "pending tail" }]);
  595. fs.mkdirSync(path.join(home, "state", "remnic", "hooks"), { recursive: true });
  596. fs.writeFileSync(cursorPath(home, "sEnd"), "0\n");
  597. const { json } = await runHook("session-end", { session_id: "sEnd", transcript_path: tpath }, { port, home });
  598. assert.equal(json.continue, true);
  599. // Cursor must be RETAINED for retry — the regression this fixes.
  600. assert.equal(fs.existsSync(cursorPath(home, "sEnd")), true, "cursor retained after failed flush");
  601. assert.equal(fs.readFileSync(cursorPath(home, "sEnd"), "utf8").trim(), "0");
  602. } finally {
  603. server.close();
  604. fs.rmSync(home, { recursive: true, force: true });
  605. }
  606. });
  607. test("session-end: removes the cursor after a successful final flush", async () => {
  608. const home = mkHome();
  609. const { server, port, calls } = await startServer((req, res) => res.writeHead(200).end("{}"));
  610. try {
  611. const tpath = transcript(home, [{ role: "user", content: "pending tail" }]);
  612. fs.mkdirSync(path.join(home, "state", "remnic", "hooks"), { recursive: true });
  613. fs.writeFileSync(cursorPath(home, "sEnd2"), "0\n");
  614. await runHook("session-end", { session_id: "sEnd2", transcript_path: tpath }, { port, home });
  615. assert.ok(calls.find((c) => c.url === "/engram/v1/observe"), "final flush observed");
  616. assert.equal(fs.existsSync(cursorPath(home, "sEnd2")), false, "cursor cleared after successful flush");
  617. } finally {
  618. server.close();
  619. fs.rmSync(home, { recursive: true, force: true });
  620. }
  621. });
  622. test("session-end: skips final flush via a symlinked cursor (state hardening)", async () => {
  623. const home = mkHome();
  624. const { server, port, calls } = await startServer((req, res) => res.writeHead(200).end("{}"));
  625. try {
  626. const stateDir = path.join(home, "state", "remnic", "hooks");
  627. fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
  628. const cursor = cursorPath(home, "sUnsafe");
  629. const symTarget = path.join(home, "target.txt");
  630. fs.writeFileSync(symTarget, "unchanged\n");
  631. fs.symlinkSync(symTarget, cursor);
  632. const tpath = transcript(home, [{ role: "user", content: "would-be-pending" }]);
  633. await runHook("session-end", { session_id: "sUnsafe", transcript_path: tpath }, { port, home });
  634. assert.equal(calls.filter((c) => c.url === "/engram/v1/observe").length, 0);
  635. assert.equal(fs.readFileSync(symTarget, "utf8"), "unchanged\n");
  636. } finally {
  637. server.close();
  638. fs.rmSync(home, { recursive: true, force: true });
  639. }
  640. });
  641. // ── token resolution ───────────────────────────────────────────────────────
  642. test("token resolution: claude-code connector wins over openclaw in tokens.json", async () => {
  643. const home = mkHome();
  644. fs.mkdirSync(path.join(home, ".remnic"), { recursive: true });
  645. fs.writeFileSync(
  646. path.join(home, ".remnic", "tokens.json"),
  647. JSON.stringify({
  648. tokens: [
  649. { connector: "openclaw", token: "openclaw-tok" },
  650. { connector: "claude-code", token: "cc-tok" },
  651. ],
  652. }),
  653. );
  654. const { server, port, calls } = await startServer((req, res) => {
  655. if (req.url === "/engram/v1/live") return res.writeHead(200).end("ok");
  656. if (req.url === "/engram/v1/recall") return res.writeHead(200).end("{}");
  657. res.writeHead(200).end("{}");
  658. });
  659. try {
  660. // No env token — must come from tokens.json.
  661. await runHook(
  662. "session-start",
  663. { session_id: "sTok", cwd: home },
  664. { port, home, env: { token: null } },
  665. );
  666. const recall = calls.find((c) => c.url === "/engram/v1/recall");
  667. assert.ok(recall, "recall was called using the tokens.json credential");
  668. } finally {
  669. server.close();
  670. fs.rmSync(home, { recursive: true, force: true });
  671. }
  672. });
  673. test("token resolution: legacy ~/.engram/tokens.json is the read fallback", async () => {
  674. const home = mkHome();
  675. fs.mkdirSync(path.join(home, ".engram"), { recursive: true });
  676. fs.writeFileSync(
  677. path.join(home, ".engram", "tokens.json"),
  678. JSON.stringify({ tokens: [{ connector: "openclaw", token: "legacy-tok" }] }),
  679. );
  680. const { server, port, calls } = await startServer((req, res) => {
  681. if (req.url === "/engram/v1/live") return res.writeHead(200).end("ok");
  682. if (req.url === "/engram/v1/recall") return res.writeHead(200).end("{}");
  683. res.writeHead(200).end("{}");
  684. });
  685. try {
  686. await runHook(
  687. "session-start",
  688. { session_id: "sLeg", cwd: home },
  689. { port, home, env: { token: null } },
  690. );
  691. const recall = calls.find((c) => c.url === "/engram/v1/recall");
  692. assert.ok(recall, "recall was called using the legacy engram token store");
  693. } finally {
  694. server.close();
  695. fs.rmSync(home, { recursive: true, force: true });
  696. }
  697. });
  698. // The documented standalone-server setup (docs/guides/standalone-server.md,
  699. // README) authenticates the daemon with REMNIC_AUTH_TOKEN and never mints a
  700. // connector token, so nothing lands in ~/.remnic/tokens.json and none of the
  701. // OPENCLAW_* names are set. Before the canonical pair was added to
  702. // resolveToken(), that shape sent an unauthenticated health probe, took a 401,
  703. // and reported "daemon not running" — silently skipping recall and observe.
  704. function authEnvServer() {
  705. const seen = { health: "unset", recall: "unset" };
  706. return startServer((req, res) => {
  707. if (req.url === "/engram/v1/live") {
  708. seen.health = req.headers.authorization || null;
  709. return res.writeHead(200).end("ok");
  710. }
  711. if (req.url === "/engram/v1/recall") {
  712. seen.recall = req.headers.authorization || null;
  713. return res
  714. .writeHead(200, { "Content-Type": "application/json" })
  715. .end(JSON.stringify({ context: "ctx", count: 1, mode: "auto" }));
  716. }
  717. res.writeHead(404).end();
  718. }).then((started) => ({ ...started, seen }));
  719. }
  720. for (const name of ["REMNIC_AUTH_TOKEN", "ENGRAM_AUTH_TOKEN"]) {
  721. test(`token resolution: ${name} authenticates health and recall (no token store)`, async () => {
  722. const home = mkHome();
  723. const { server, port, seen } = await authEnvServer();
  724. try {
  725. const res = await runHook(
  726. "session-start",
  727. { session_id: "sEnv", cwd: home },
  728. { port, home, env: { token: null, extra: { [name]: "operator-secret" } } },
  729. );
  730. assert.equal(seen.health, "Bearer operator-secret");
  731. assert.equal(seen.recall, "Bearer operator-secret");
  732. assert.doesNotMatch(
  733. res.json.hookSpecificOutput.additionalContext,
  734. /daemon not running/,
  735. "an authenticated daemon must not be reported as down",
  736. );
  737. } finally {
  738. server.close();
  739. fs.rmSync(home, { recursive: true, force: true });
  740. }
  741. });
  742. }
  743. test("token resolution: OPENCLAW_REMNIC_ACCESS_TOKEN outranks REMNIC_AUTH_TOKEN", async () => {
  744. const home = mkHome();
  745. const { server, port, seen } = await authEnvServer();
  746. try {
  747. await runHook(
  748. "session-start",
  749. { session_id: "sPrec", cwd: home },
  750. { port, home, env: { token: "connector-tok", extra: { REMNIC_AUTH_TOKEN: "operator-secret" } } },
  751. );
  752. // Both are current names; the connector-scoped one stays first, so an
  753. // install that already worked keeps its existing credential.
  754. assert.equal(seen.health, "Bearer connector-tok");
  755. } finally {
  756. server.close();
  757. fs.rmSync(home, { recursive: true, force: true });
  758. }
  759. });
  760. test("token resolution: REMNIC_AUTH_TOKEN outranks the legacy OPENCLAW_ENGRAM_ACCESS_TOKEN", async () => {
  761. const home = mkHome();
  762. const { server, port, seen } = await authEnvServer();
  763. try {
  764. await runHook(
  765. "session-start",
  766. { session_id: "sLegacyPrec", cwd: home },
  767. {
  768. port,
  769. home,
  770. env: {
  771. token: null,
  772. extra: {
  773. OPENCLAW_ENGRAM_ACCESS_TOKEN: "stale-legacy-tok",
  774. REMNIC_AUTH_TOKEN: "operator-secret",
  775. },
  776. },
  777. },
  778. );
  779. // Primary-before-legacy (AGENTS.md §9). A migrated deployment often still
  780. // exports the pre-rename alias; if that stale value outranked the token
  781. // the daemon actually runs with, the probe would 401 and land back on
  782. // "daemon not running".
  783. assert.equal(seen.health, "Bearer operator-secret");
  784. } finally {
  785. server.close();
  786. fs.rmSync(home, { recursive: true, force: true });
  787. }
  788. });
  789. test("token resolution: tokens.json still outranks REMNIC_AUTH_TOKEN", async () => {
  790. const home = mkHome();
  791. fs.mkdirSync(path.join(home, ".remnic"), { recursive: true });
  792. fs.writeFileSync(
  793. path.join(home, ".remnic", "tokens.json"),
  794. JSON.stringify({ tokens: [{ connector: "claude-code", token: "cc-tok" }] }),
  795. );
  796. const { server, port, seen } = await authEnvServer();
  797. try {
  798. await runHook(
  799. "session-start",
  800. { session_id: "sStore", cwd: home },
  801. { port, home, env: { token: null, extra: { REMNIC_AUTH_TOKEN: "operator-secret" } } },
  802. );
  803. assert.equal(seen.health, "Bearer cc-tok");
  804. } finally {
  805. server.close();
  806. fs.rmSync(home, { recursive: true, force: true });
  807. }
  808. });
  809. // ── hooks.json Windows parity ─────────────────────────────────────────────
  810. test("hooks.json: every event uses cross-platform exec form with ${CLAUDE_PLUGIN_ROOT} (#1518)", () => {
  811. const cfg = JSON.parse(
  812. fs.readFileSync(path.join(__dirname, "..", "hooks.json"), "utf8"),
  813. );
  814. const eventToHookName = (event) => {
  815. switch (event) {
  816. case "SessionStart": return "session-start";
  817. case "PostToolUse": return "post-tool-observe";
  818. case "UserPromptSubmit": return "user-prompt-recall";
  819. default: throw new Error(`unexpected event ${event}`);
  820. }
  821. };
  822. for (const event of ["SessionStart", "PostToolUse", "UserPromptSubmit"]) {
  823. const matchers = cfg.hooks[event] || [];
  824. for (const matcher of matchers) {
  825. for (const hook of matcher.hooks) {
  826. // Claude Code hooks do not support `commandWindows` (that field is
  827. // specific to the Codex plugin loader). The documented cross-
  828. // platform shape is exec form: `command: "node"` with an `args`
  829. // vector pointing at the runner. `node.exe` is a real binary on
  830. // Windows, so the same entry works on every platform without a
  831. // shell, without Git Bash, and without `.sh`/`.ps1` dispatch.
  832. // Each `args` element is passed verbatim (no shell tokenization),
  833. // so a plugin root containing spaces or metacharacters such as `$`
  834. // or backticks cannot be re-interpreted by a shell.
  835. assert.equal(
  836. hook.command,
  837. "node",
  838. `${event}.command must be the bare executable "node" (exec form)`,
  839. );
  840. assert.ok(
  841. Array.isArray(hook.args) && hook.args.length >= 2,
  842. `${event} must declare an args vector [runner, event-name]`,
  843. );
  844. assert.ok(
  845. typeof hook.args[0] === "string" &&
  846. hook.args[0].startsWith("${CLAUDE_PLUGIN_ROOT}/hooks/bin/remnic-cc-hook.cjs"),
  847. `${event}.args[0] must point at the bundled runner via \${CLAUDE_PLUGIN_ROOT}, got: ${hook.args && hook.args[0]}`,
  848. );
  849. assert.equal(hook.args[1], eventToHookName(event),
  850. `${event}.args[1] must be the hook event name`);
  851. // The shell-form fields must NOT be present: no `commandWindows`
  852. // (unsupported by Claude Code), and `command` must not be a shell
  853. // string that would let a shell re-tokenize the plugin root.
  854. assert.ok(
  855. hook.commandWindows === undefined,
  856. `${event} must not declare commandWindows (Claude Code ignores it; exec form is the cross-platform path)`,
  857. );
  858. }
  859. }
  860. }
  861. });
  862. test("plugin.json: manifest conforms to the Claude Code plugin schema (author is an object)", () => {
  863. const manifest = JSON.parse(
  864. fs.readFileSync(path.join(__dirname, "..", "..", ".claude-plugin", "plugin.json"), "utf8"),
  865. );
  866. // Claude Code's plugin-manifest validator rejects a string `author`
  867. // ("Invalid input: expected object, received string"), which blocks
  868. // installing this plugin from a Claude Code marketplace. `author` must be an
  869. // object carrying at least a `name`.
  870. assert.equal(typeof manifest.author, "object", "author must be an object, not a string");
  871. assert.ok(manifest.author !== null && !Array.isArray(manifest.author), "author must be a plain object");
  872. assert.equal(typeof manifest.author.name, "string", "author.name must be a string");
  873. assert.ok(manifest.author.name.length > 0, "author.name must be non-empty");
  874. // Sanity-check the other required identity fields while we're here.
  875. assert.equal(typeof manifest.name, "string", "name must be a string");
  876. assert.equal(typeof manifest.version, "string", "version must be a string");
  877. });
  878. test("runner source: payload fields never reach a shell — spawn uses fixed argv (#1518 guard shell interpolation)", () => {
  879. const src = fs.readFileSync(CORE, "utf8");
  880. // Every spawn/spawnSync must use a fixed literal argument array, never a
  881. // string command, so a payload value (session id, cwd, transcript path,
  882. // prompt, tool name) cannot achieve command injection.
  883. assert.doesNotMatch(
  884. src,
  885. /spawn(Sync)?\(\s*`/m,
  886. "spawn/spawnSync must never take a template-literal command (shell injection risk)",
  887. );
  888. assert.doesNotMatch(
  889. src,
  890. /execFileSync\(\s*`|exec\(\s*`/m,
  891. "exec/execFileSync must never take a template-literal command",
  892. );
  893. // Confirm the daemon-start + migration loops pre-check PATH with onPath()
  894. // (.cmd/.exe-aware) so the remnic→engram fallthrough happens, and launch
  895. // through a shell on Windows so `.cmd` npm shims actually run.
  896. const onPathHits = (src.match(/onPath\(bin\)/g) || []).length;
  897. assert.ok(onPathHits >= 2, "both migration and daemon-start loops must PATH-gate with onPath()");
  898. assert.match(
  899. src,
  900. /shell:\s*process\.platform === "win32"/,
  901. "CLI launches must use a shell on Windows so .cmd shims run",
  902. );
  903. });
  904. test("runner source: stdin is the single payload source — no env-var override", () => {
  905. const src = fs.readFileSync(CORE, "utf8");
  906. assert.doesNotMatch(
  907. src,
  908. /process\.env\.REMNIC_HOOK_INPUT/,
  909. "readStdin must not consult REMNIC_HOOK_INPUT (env-leak override risk)",
  910. );
  911. });
  912. test("runner source: path inputs are type-validated before use (#1518 validate path types)", () => {
  913. const src = fs.readFileSync(CORE, "utf8");
  914. // cwd / transcript_path are coerced via `input.X || ""` so an unexpected
  915. // non-string payload field (number, object, array) cannot reach fs / git
  916. // and throw an opaque error or, worse, be coerced by Node to a path.
  917. assert.match(src, /const cwd = input\.cwd \|\| ""/, "cwd must be defaulted to empty string");
  918. assert.match(
  919. src,
  920. /const transcriptPath = input\.transcript_path \|\| ""/,
  921. "transcript_path must be defaulted to empty string",
  922. );
  923. });
  924. test("token resolution: REMNIC_AUTH_TOKEN outranks ENGRAM_AUTH_TOKEN when both are set", async () => {
  925. const home = mkHome();
  926. const { server, port, seen } = await authEnvServer();
  927. try {
  928. await runHook(
  929. "session-start",
  930. { session_id: "sBothCanonical", cwd: home },
  931. {
  932. port,
  933. home,
  934. env: {
  935. token: null,
  936. extra: { REMNIC_AUTH_TOKEN: "current-tok", ENGRAM_AUTH_TOKEN: "legacy-tok" },
  937. },
  938. },
  939. );
  940. assert.equal(seen.health, "Bearer current-tok");
  941. assert.equal(seen.recall, "Bearer current-tok");
  942. } finally {
  943. server.close();
  944. fs.rmSync(home, { recursive: true, force: true });
  945. }
  946. });
  947. test("health probe uses the same bearer as the operation it gates", async () => {
  948. const home = mkHome();
  949. const { server, port, seen } = await authEnvServer();
  950. try {
  951. // REMNIC_HOOK_TOKEN is the detached observe worker's internal propagation
  952. // channel; the foreground handlers never read it. If the probe consulted
  953. // it, an inherited value would authenticate health with one bearer while
  954. // recall sent another — a false "healthy" followed by a 401, or the
  955. // reverse. Probe and operation must carry one snapshot.
  956. await runHook(
  957. "session-start",
  958. { session_id: "sSnapshot", cwd: home },
  959. { port, home, env: { extra: { REMNIC_HOOK_TOKEN: "inherited-worker-tok" } } },
  960. );
  961. assert.equal(seen.health, "Bearer test-token");
  962. assert.equal(seen.recall, seen.health);
  963. } finally {
  964. server.close();
  965. fs.rmSync(home, { recursive: true, force: true });
  966. }
  967. });

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.