CodeNomad/scripts/fixtures/memory-instructions
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
..
plugin.mjs feat(memory): add opt-in persistent agent memory (#1313) 2026-11-06 15:29:24 +01:00