mirror of
https://github.com/NeuralNomadsAI/CodeNomad.git
synced 2026-11-17 05:49:28 +00:00
## 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.
150 lines
10 KiB
JavaScript
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}`)
|
|
}
|
|
}
|