CodeNomad/scripts/test-memory-instructions-native.mjs
Pascal André 0829c7cfe6
feat(memory): add opt-in persistent agent memory (#1313)
## Why

Let agents retain useful facts and preferences across conversations
without relying on hand-written user context or sending memory to a
remote service. Memory is opt-in and belongs to the connected CodeNomad
configuration.

## User-visible behavior

- Add **Memory** under **Preferences → General**, also available in
embedded Settings; it is **disabled by default**.
- Provide **About you** (60 entries) and **Project** (200 entries). The
server derives project identity from the normalized Git remote, with a
canonical local-path fallback shared by worktrees.
- Expose `codenomad_memory` for listing, reading, saving and forgetting
agent-written entries. Each accepted save or deletion creates a local
Git commit.
- Synchronize the session-local `codenomad.memory` instructions,
including native children: recording rules plus bounded title/type
lists, with read-before-action and verification guidance.
- Review New/Modified badges, edit entries directly, confirm Forget,
resolve stale revisions, and inspect suspicious entries excluded from
agent use.
- **Tidy up** (**Ranger** in French) opens a project-bound session to
verify and merge the selected scope, preserving unverifiable claims and
external references.
- Existing external agent memory stays under its own management; agents
can store a literal Reference to it. No automatic import or remote
synchronization.

## Approach and edge cases

- Server-owned Markdown entries in the configuration's private Git
repository, atomic file replacement, process-generation-fenced locking
and recoverable local commit transactions.
- Shared validation contracts, 60-character titles and 2,000-character
bodies, multilingual duplicate matching and injection heuristics across
all ten interface languages. Flagged entries remain reviewable and count
toward capacity, but are rechecked and excluded from agent projections.
- Missing folders are empty; malformed/unreadable scopes return explicit
errors. Capacity errors ask the agent to merge or remove entries.
Revision checks preserve concurrent edits and drafts.
- Bundle the native memory plugin through the existing native-plugin
build/provisioning lifecycle, including the managed-plugin descriptor
used by the current dev branch.
- Authorize session/project ownership and enablement at mutation time.
Optional instruction capability absence stays silent. Ordinary sends
continue during optional memory outages; stale instruction cleanup is
best-effort and memory claims must still be verified.
- Rebased onto `origin/dev`; preserved its graceful shutdown lifecycle,
nested-worktree error handling and translated keep-awake help alongside
memory.

## Documentation

- Updated `docs/help/en/settings.md` and all nine translations with
activation, scopes, editing, forgetting/history retention, warnings,
Tidy up, external references and local-only storage.
- Added the agent-memory developer contract and updated the related
settings, project, plugin and OpenCode integration guidance.

## Validation

- Focused memory/server suite, including
`packages/server/src/memory/integration.test.ts`, native memory tool
units, session memory context, project/forge identity, standalone
authenticated bridge, nested-worktree and Git-probe regressions: **115
passed, 0 failed, 1 skipped** (real WSL qualification is opt-in).
- Admission, plugin installation/lifecycle/provisioning, managed-plugin
recognition, graceful shutdown, cleanup and shared UI contract
regressions: **127 passed**.
- `npm run typecheck` (remote tunnel, UI and Electron): **passed**.
- `npm run typecheck --workspace @neuralnomads/codenomad`: **passed**.
- Memory and Preferences browser tests (`agent-memory`,
`preferences-window`, `preferences-startup`,
`preferences-startup-state`, serial): **38 passed**.
- `npm run test:help`: **31 passed**, including all ten locales'
structure and links.
- `npm run build:memory --workspace @neuralnomads/codenomad` plus
native-plugin build, managed-plugin and desktop resource checks: **36
passed**. Verified the built memory bundle's first-line plugin
descriptor.
- `git diff --check`: **passed**; checkout clean and branch contains the
current fetched `origin/dev` before its first push.

## Known test noise

`missions/mission-local-sources.test.ts:73` also fails on `origin/dev`.
Four intermittent full-suite failures outside memory are being compared
with `origin/dev`; these are separate from the focused post-rebase
checks above.
2026-11-06 15:29:24 +01:00

150 lines
10 KiB
JavaScript

// Private daemon and deterministic loopback provider: parent entry inheritance and
// awaited native prompt-hook writes before a native child's very first model call.
import assert from "node:assert/strict"
import { spawn } from "node:child_process"
import { randomUUID } from "node:crypto"
import { mkdir, mkdtemp, writeFile } from "node:fs/promises"
import { createServer } from "node:http"
import path from "node:path"
import { fileURLToPath } from "node:url"
import { setTimeout as delay } from "node:timers/promises"
import { build } from "esbuild"
import { OpenCode } from "@opencode/client"
import { nativePluginBuild } from "../packages/server/scripts/native-plugin-build.mjs"
import { readMemoryInstructionsCapability } from "../packages/server/src/memory/instructions-capability.ts"
import { fixtureEnvironment, fixtureParent } from "./native-product-fixture.mjs"
import { stopFixtureChild } from "./native-fixture-guards.mjs"
const cli = process.argv[2]
assert(cli && path.isAbsolute(cli), "Pass an absolute isolated CLI executable path")
const root = await mkdtemp(path.join(await fixtureParent(), "memory-instructions-"))
const config = path.join(root, "config"), state = path.join(root, "state.json"), plugin = path.join(root, "memory-proof")
await mkdir(config)
await mkdir(plugin)
await writeFile(path.join(plugin, "package.json"), JSON.stringify({ name: "codenomad-memory-proof", type: "module", exports: "./index.mjs" }))
await writeFile(state, JSON.stringify({ enabled: false, revision: 0 }))
await build({ ...nativePluginBuild, entryPoints: [fileURLToPath(new URL("./fixtures/memory-instructions/plugin.mjs", import.meta.url))], outfile: path.join(plugin, "index.mjs") })
const requests = []
let providerError
const provider = createServer(async (request, response) => {
try {
let raw = ""
for await (const chunk of request) raw += chunk
const body = JSON.parse(raw)
assert(requests.length < 60, "Provider request budget")
requests.push(body)
const tools = (body.tools ?? []).map(tool => tool.function?.name)
const last = JSON.stringify(body.messages.at(-1))
const launch = body.stream && /PARENT_(BASELINE|HOOK)/.test(last) && tools.includes("subagent")
if (!body.stream) {
response.setHeader("content-type", "application/json")
return response.end(JSON.stringify({ id: "fixture", choices: [{ message: { role: "assistant", content: "Memory proof" }, finish_reason: "stop" }] }))
}
const delta = launch ? { role: "assistant", tool_calls: [{ index: 0, id: `call_${requests.length}`, type: "function", function: {
name: "subagent", arguments: JSON.stringify({ agent: "general", description: "Memory proof", prompt: last.includes("PARENT_BASELINE") ? "CHILD_BASELINE" : "CHILD_HOOK" }),
} }] } : { role: "assistant", content: "DONE" }
response.setHeader("content-type", "text/event-stream")
for (const [value, finish_reason] of [[delta, null], [{}, launch ? "tool_calls" : "stop"]]) {
response.write(`data: ${JSON.stringify({ id: "fixture", object: "chat.completion.chunk", model: "fixture", choices: [{ index: 0, delta: value, finish_reason }] })}\n\n`)
}
response.end("data: [DONE]\n\n")
} catch (error) { providerError = error; response.destroy() }
})
await new Promise(resolve => provider.listen(0, "127.0.0.1", resolve))
const password = randomUUID()
const env = await fixtureEnvironment(root, {
OPENCODE_CONFIG_DIR: config, OPENCODE_DB: path.join(root, "fixture.db"), OPENCODE_CONFIG_PROJECT_DISABLE: "1",
OPENCODE_DISABLE_MODELS_FETCH: "1", OPENCODE_DISABLE_FFF: "1", OPENCODE_SERVER_PASSWORD: password,
OPENCODE_CONFIG_CONTENT: JSON.stringify({ update: "disable", snapshots: false, model: "fixture/fixture",
plugins: [{ package: plugin, options: { state } }], providers: { fixture: {
package: "@opencode/ai/providers/openai-compatible", settings: { baseURL: `http://127.0.0.1:${provider.address().port}/v1`, apiKey: "fixture-only" }, models: { fixture: {} },
} } }),
})
let output = "", spawnError
const child = spawn(cli, ["serve", "--hostname", "127.0.0.1", "--port", "0", "--print-logs"], { cwd: root, env, windowsHide: true })
const stopped = new Promise(resolve => child.once("close", resolve))
child.on("error", error => { spawnError = error })
child.stdout.on("data", data => { output += data }); child.stderr.on("data", data => { output += data })
async function until(predicate, label) {
const deadline = Date.now() + 45_000
while (!await predicate()) {
if (spawnError) throw spawnError
if (providerError) throw providerError
assert(child.exitCode === null && Date.now() < deadline, `${label}: ${output.slice(-3000)}`)
await delay(50)
}
}
try {
await until(() => /http:\/\/127\.0\.0\.1:\d+/.test(output), "private serve")
const endpoint = { url: output.match(/http:\/\/127\.0\.0\.1:\d+/)[0], auth: { type: "basic", username: "opencode", password } }
const fetcher = (url, init) => fetch(url, { ...init, signal: AbortSignal.any([...(init?.signal ? [init.signal] : []), AbortSignal.timeout(30_000)]) })
const client = OpenCode.make({ baseUrl: endpoint.url, fetch: fetcher, headers: { authorization: `Basic ${Buffer.from(`opencode:${password}`).toString("base64")}` } })
const capability = await readMemoryInstructionsCapability({ endpoint, fetch: fetcher, assertCurrent() {} })
assert.equal(capability, "supported")
const info = await client.server.info()
console.log(`Runtime: ${info.version}`)
const location = { directory: root }
const entries = sessionID => client.session.instructions.entry.list({ sessionID })
const ownEntry = async sessionID => (await entries(sessionID)).find(entry => entry.key === "codenomad.memory")
async function run(label) {
const session = await client.session.create({ location })
await client.session.instructions.entry.put({ sessionID: session.id, key: "codenomad.memory", value: "PARENT_MEMORY_CANARY" })
const start = requests.length
await client.session.prompt({ sessionID: session.id, text: `PARENT_${label}` })
await until(async () => (await client.session.list({ location, parentID: session.id, limit: 20 })).data.length === 1, "native child creation")
const descendant = (await client.session.list({ location, parentID: session.id, limit: 20 })).data[0]
await until(() => requests.slice(start).some(body => body.stream && JSON.stringify(body.messages.at(-1)).includes(`CHILD_${label}`)), "native child model request")
await client.session.wait({ sessionID: descendant.id }, { signal: AbortSignal.timeout(30_000) })
await client.session.wait({ sessionID: session.id }, { signal: AbortSignal.timeout(30_000) })
const firstChildRequest = requests.slice(start).find(body => body.stream && JSON.stringify(body.messages.at(-1)).includes(`CHILD_${label}`))
return { session, descendant, firstChildRequest }
}
const baseline = await run("BASELINE")
const inherited = await ownEntry(baseline.descendant.id)
console.log(`Baseline child instruction entry: ${inherited ? "inherited" : "absent"}`)
assert.equal(inherited, undefined, "The qualified runtime gives native children their own instruction entries")
assert.doesNotMatch(JSON.stringify(baseline.firstChildRequest.messages.filter(message => message.role === "system")), /PARENT_MEMORY_CANARY/)
await writeFile(state, JSON.stringify({ enabled: true, revision: 1 }))
const hooked = await run("HOOK")
const written = await ownEntry(hooked.descendant.id)
assert(written, "The admission hook wrote the child's own named entry")
assert.match(JSON.stringify(written), new RegExp(hooked.descendant.id))
const system = JSON.stringify(hooked.firstChildRequest.messages.filter(message => message.role === "system"))
assert.match(system, /NATIVE_MEMORY_CANARY/)
assert.match(system, new RegExp(hooked.descendant.id))
assert.doesNotMatch(system, /PARENT_MEMORY_CANARY/)
console.log("PASS parent entries are session-local; awaited native prompt hook installs the child's own entry before its first provider request, outside the proxy")
await writeFile(state, JSON.stringify({ enabled: true, revision: 2 }))
const start = requests.length
await client.session.prompt({ sessionID: hooked.descendant.id, text: "CHILD_REFRESH" })
await until(() => requests.length > start, "fresh native child admission")
await client.session.wait({ sessionID: hooked.descendant.id }, { signal: AbortSignal.timeout(30_000) })
assert.match(JSON.stringify(await ownEntry(hooked.descendant.id)), /"revision":2/)
const refreshed = JSON.stringify(requests.slice(start).find(body => body.stream).messages)
assert.ok(/revision[^\d]*2/.test(refreshed), "A resumed request receives the fresh entry through the native context-update notice")
console.log("PASS resumed native child refreshes the entry at its next admission through the native context-update notice")
await client.session.instructions.entry.put({ sessionID: hooked.descendant.id, key: "other-owner", value: "OTHER_OWNER_CANARY" })
await client.session.instructions.entry.remove({ sessionID: hooked.descendant.id, key: "codenomad.memory" })
assert.equal(await ownEntry(hooked.descendant.id), undefined)
assert.ok((await entries(hooked.descendant.id)).some(entry => entry.key === "other-owner"))
console.log("PASS removing the memory entry preserves other owners' instruction keys")
await writeFile(state, JSON.stringify({ enabled: true, refuse: true }))
const failed = await client.session.create({ location })
const beforeFailure = requests.length
await assert.rejects(client.session.prompt({ sessionID: failed.id, text: "FAILURE_PROOF" }))
assert.equal(requests.length, beforeFailure, "An independent mandatory prompt hook admits no provider request")
assert.equal((await client.session.inbox.list({ sessionID: failed.id })).length, 0)
console.log("PASS an independent mandatory native admission gate still rejects input before any provider call or inbox entry")
} finally {
try { await stopFixtureChild(child, stopped) } finally {
provider.closeAllConnections()
await new Promise(resolve => provider.close(resolve))
await writeFile(path.join(root, "daemon.log"), output)
console.log(`Isolated fixture: ${root}`)
}
}