Skip to content

Latest commit

 

History

History
489 lines (429 loc) · 30.6 KB

AGENT_MEMORY.md

File metadata and controls

489 lines (429 loc) · 30.6 KB

Agent memory contracts

Entry model

packages/server/src/memory/contract.ts owns the dependency-free shared data contract, exported to UI clients through packages/server/src/api-types.ts. memory/model.ts owns validation and limits:

  • Scopes: global (60 entries) and project (200 entries).
  • Types: fact, preference, reference.
  • Markdown header: id, title, type, createdAt, updatedAt, sessionId.
  • Content: text, preserved by validation; at most 2,000 Unicode code points.
  • Title: nonblank, single-line, at most 60 Unicode code points.
  • IDs: one portable filename segment, 1–128 ASCII letters, digits, underscores or hyphens, beginning with a letter or digit; Windows device names are rejected.
  • Dates: ISO datetimes with a timezone; session provenance is required.

validateMemoryContent validates mutation input. validateMemoryEntry validates the complete header and content; storage readers pass malformed as the error code. Unknown fields fail validation. MemoryError carries one of disabled, full, conflict, invalid, unreadable, git_unavailable, malformed, and an optional title list for capacity errors. UI callers translate codes and keep underlying filesystem, Git and configuration errors private.

Project identity

memory/project-identity.ts resolves an already-authorized session directory. The server owns this input. An identity establishes the memory namespace; directory authorization remains with workspace/session ownership.

The selected remote is origin, otherwise the lexically first remote name. forge/remote.ts supplies one shared validated parser with separate repository and forge policies. Repository normalization accepts HTTP(S), SSH, Git and SCP-style network addresses, strips credentials, query, fragment, surrounding slashes and .git, lowercases the host, preserves repository path case and every explicit port, and produces authority/repository-path. Equivalent SSH/SCP and HTTPS addresses without explicit ports share an identity. Repository identity decodes and re-encodes each path segment with canonical UTF-8 percent escapes, sharing encoded/decoded spaces and Unicode spellings. Empty, dot-only, control and encoded path-separator segments fail validation. Forge web links retain their strict ASCII path policy.

An absent or unparseable selected remote uses the shared repository's physical root: the parent of its common .git directory, or the physical common Git directory for bare/separate layouts. Subfolders and linked worktrees therefore share the local fallback. A verified non-Git directory uses its own real path. Other Git/discovery failures return an error. Windows host fallback paths are case-folded. WSL executes Git and realpath in the selected distro and preserves Linux path case; local fallbacks include the case-folded distro name. Both WSL UNC spellings resolve through that execution-host adapter. Identity reads clear inherited GIT_* overrides on the host. The WSL adapter also unsets Git's repository-local, discovery and configuration redirection variables inside the selected distro before invoking Git or realpath.

The namespace is SHA-256 of remote:<normalized-remote> or local:<canonical-local-path>. Only the hash and source kind leave the resolver; remote credentials and physical fallback paths stay private. Callers resolve again for authoritative operations so remote edits and session moves take effect.

Local storage and Git transactions

memory/store.ts constructs MemoryStore from ConfigLocation.baseDir. The server's listeners share this instance. Its lazily initialized repository is <baseDir>/memory/, with global/<id>.md and projects/<projectId>/<id>.md. Project IDs use the resolver's SHA-256 namespace. Missing folders read as empty; invalid UTF-8, malformed or extra header fields, duplicate YAML keys, filename/header mismatches, symbolic links and unreadable files produce explicit scope errors. Storage bounds encoded files and journals to 16 KiB and preserves Markdown content, including trailing whitespace and line endings.

Entries use UTF-8 Markdown with a YAML frontmatter block delimited by ---, followed immediately by the literal body:

---
id: build-command
title: Build command
type: fact
createdAt: '2026-01-01T00:00:00Z'
updatedAt: '2026-01-01T00:00:00Z'
sessionId: ses_example
---
Run npm run build from the repository root.

The repository remains local to the CodeNomad configuration. Saves, duplicate replacement and deletion retain the previous text in its Git history; forgetting an entry removes it from active memory. Treat stored secrets as sensitive across that full history. External memory belongs in a literal reference entry.

The server policy calls mutate(namespace, decide) to read a fresh scope and choose { kind: "save", entry, result }, { kind: "delete", id, result } or { kind: "none", result }. The callback owns enablement, capacity, deduplication and preservation of entry identity/provenance. Its decision and the resulting commit share one repository-wide interprocess lock. list and read use the same lock for existing storage; pristine empty reads leave the filesystem unchanged. read resolves an exact ID first, then an exact title among safe entries. list and read expose the agent-safe projection. listForUI returns every entry with a freshly computed flagged boolean for human review.

Writes fsync a uniquely named temporary in the destination directory, then rename over the target. A failed replacement preserves the target and removes the pending journal. Before publication, an atomic .transaction.json records the intended file operation and its unique transaction ID. A failed commit keeps that journal, and later access completes the operation and its commit before returning data. Interrupted deletions follow the same roll-forward policy. Each accepted write has a commit, including identical content. Recovery recognizes the transaction ID and tree at the current commit to avoid duplicate history. Corrupt recovery data fails explicitly.

memory/lock.ts atomically publishes a populated memory.lock/ directory next to the repository. Its owner records a nonce, PID, native process-start identity, hostname and platform. The shared host-lifetime/process-identity.ts adapter qualifies the process generation: Linux boot ID/start ticks, Windows creation ticks or the macOS native creation identity. The current process caches its own qualified identity. When its native probe is unavailable, it retains a private random memory-self: generation nonce for its lifetime. Its own lookups recognize that nonce; another process preserves such an owner while its PID is live or unknown, and recovers it after a confirmed exit. macOS execution uses the bundled process-identity helper built by build:host-helpers.

Contenders wait up to 30 seconds for a matching live owner. A confirmed exit or a different start identity proves that the recorded generation ended, including when its PID belongs to another live process. Unknown process evidence and a different execution host yield an explicit conflict while preserving ownership. Records containing only a PID qualify for recovery after a confirmed PID exit. After probing, the contender rereads the exact owner before recovery, fencing a normal release and successor publication during the probe. Age remains only an operation timeout; never use it to infer owner death.

Release verifies the nonce before each retirement attempt and retries Windows sharing violations for up to 30 seconds. Atomic retirement frees the public name before private-directory cleanup. Cleanup retries apply only to that private directory; residual private artifacts leave future acquisition free. Recovery keeps a nonempty memory.lock.dead-<nonce>/ marker so concurrent recovery attempts cannot move a successor's lock into the same destination. These small fencing markers remain beside the repository while an old recovery participant can resume. After publishing the lock and before admitting its writer, acquisition scans the populated candidate directories. Live, unknown, foreign or malformed participants retain every marker; absent or proven-dead participants permit their removal. Every old reaper published its candidate before observing the retired owner. New contenders can observe only the currently held lock, keeping cleanup safe across concurrent arrivals. Failed maintenance retains markers for the next acquisition.

memory/git.ts uses runGitProcess and requireHostGit. Missing host Git keeps the shared git_required failure contract. A timed-out, killed, unsuccessful or invalid availability probe yields a retryable memory conflict, preserving the five-second probe deadline and leaving publication for a later attempt. Git commands explicitly name the private repository and worktree, clear inherited GIT_* overrides, ignore system/global Git configuration and use the local identity CodeNomad Memory <memory@codenomad.local>. Template hooks, runtime hooks, signing, automatic GC, fsmonitor and content filters are bypassed. Per-transaction indexes and Git plumbing write exact bytes, commit and compare-and-swap the local branch; the ordinary index is published after the commit. Unrecoverable Git metadata or filesystem errors leave memory unavailable until the storage is repaired.

Duplicate, capacity and safety rules

memory/rules.ts applies duplicate and capacity decisions inside the store's locked mutation callback. MemoryStore.save(namespace, content, sessionId, enabled, id?) checks the current enablement through the supplied synchronous callback under that same lock. Successful saves return only { id, flagged } after the local commit. The lower-level mutate callback remains available to owned policy consumers; it receives all stored entries, including flagged ones.

Titles compare after Unicode NFKC normalization, lowercasing, trimming and whitespace collapsing. Exact title matches take priority. Otherwise distinct significant text words use Jaccard similarity at a threshold of 0.75, requiring at least four words on each side. Intl.Segmenter performs word segmentation with a fixed en locale; its Unicode segmentation covers mixed-language text. Stopwords from all ten UI languages apply together. Tokens must contain a Unicode letter, excluding numbers while preserving names such as node22. The highest score wins; ties resolve by ascending portable entry ID. Each save replaces at most one entry, preserving its ID and creation time while updating content, time and session.

Explicit-ID edits preserve the selected entry and report conflict when duplicate selection resolves to another entry. New entries at the exact 60/200 limits produce full, with titles and a merge-or-delete instruction. Replacements remain available at capacity. Flagged entries count toward capacity; the safe save API includes only safe titles in its capacity diagnostics. Human clients can inspect all titles through listForUI.

memory/language-data.ts contains stopwords and suspicious override, safety-bypass and credential-exfiltration patterns for en, fr, de, es, he, ja, ne, ru, tr and zh-Hans, plus role-spoofing markers. Both title and text are checked after NFKC/case normalization and removal of invisible format controls. Every read recomputes the flag from current file contents, so external edits take effect immediately. Agent reads omit flagged entries entirely; human review retains their content. Patterns are conservative heuristics: consumers must continue treating all memory as untrusted data. Reference entries are stored, compared and reviewed as literal text. Never resolve their URLs or filesystem targets.

Authorized HTTP operations

memory/api.ts validates the shared UI/tool operation contract from memory/contract.ts. POST /api/memory takes { operation, context? }; operations are list, read with query (exact ID first, then title), save with content, and delete. Every operation names scope: global | project. Project UI calls carry the existing Preferences context as { workspaceId, directory? }; the server resolves that opened record and authorizes the directory before deriving its namespace. The UI edits existing agent entries and preserves their session provenance. Agent writes record the invoking native session.

GET /api/memory/settings reads the sole server.memoryEnabled preference; absence means disabled. PUT takes { enabled: boolean }. Its writes and all HTTP configuration patches share the memory repository lock with mutations. Mutation callbacks freshly read configuration authority under that lock, then reject disabled writes. Human review remains readable while disabled. Disabling uses the lock independently of stored entry parsing, so malformed scopes remain disableable. Settings writes refresh authoritative configuration before merging to preserve external fields. Speech URL/credential pairing reads that same fresh configuration inside the write lock, together with its merge, for document and owner patches.

Reads return content-derived SHA-256 revisions over all entry fields. Explicit-ID saves and deletes require the displayed revision; stale or missing entries yield conflict. Mutations revalidate current session/project ownership under the repository lock before publication. Reads, lists and mutation acknowledgements revalidate ownership, the resolved namespace and agent enablement after storage awaits, including the UI writability probe. Session title preparation also revalidates the project identity after its scope reads. Implicit agent saves retain duplicate replacement policy. UI entries include freshly computed flagged and, when flagged, warning: suspected_injection. Agent lists contain safe headers and revisions; reads contain safe text; save acknowledgements contain only ID, revision and flag. Safe capacity errors include safe titles and a merge-or-delete instruction. Errors expose only the shared business code and fixed safe copy.

The native sendMemoryInput transport uses the existing loopback registration, local token and WSL bridge adapter. memory-probe checks the native session's current location against the backend's authorized directories, independently of desktop/browser capabilities; memory-input repeats ownership at execution. Discovery requires exactly one owning backend. UI paths use ordinary browser authentication; native admission grants access only to the private bridge path. WSL Windows-registry discovery runs asynchronous, cancellable interop commands; a qualified path is cached, and cancelled or failed discovery remains retryable. After successful commits/settings changes, memory.changed invalidates readers without carrying entry content, titles, IDs or directory information.

Bundled native tool

opencode/memory/desktop-plugin.ts supplies codenomad_memory while a live backend presence lease requests memory. opencode/memory/preference.ts writes server.memoryEnabled into every memory lease of the backend ({"version":1,"memory":true}, or an empty lease) at startup and on each storage.configChanged for the server or * owner; an unreadable or invalid preference requests nothing. The plugin registers its tool transform conditionally, reads the request through observeMemoryRequest at each presence interval and calls ctx.tool.reload() only when it changes, so running sessions gain or lose the tool within seconds. The prompt hook stays registered with presence, so disabling memory still removes stale codenomad.memory instructions. A runtime without ctx.tool.reload keeps the tool registered and execution rejects disabled use. Its four actions require scope; read takes query (exact ID or title), save takes title, type, text, and an explicit edit additionally takes id and revision; delete requires id and revision from a fresh read. The plugin derives provenance from tool.sessionID and delegates every operation to sendMemoryInput. Safe capacity titles reach the agent with a merge-or-delete instruction. An unconfirmed write instructs a list/read verification before another decision to write.

build:memory uses the common native bundle settings. The desktop and standalone server provision its content-addressed payload through DesktopPluginLifecycle once their loopback bridge publication succeeds. Leases keep the tool's registration aligned with backend presence, including withdrawal and reopening.

Session instruction synchronization

workspaces/session-memory-context.ts owns the single codenomad.memory entry. The authorized proxy refreshes it before prompt and command sends. Missions assignment/report/recovery inputs and lifecycle resume synthetics refresh it at their own admission boundaries. Their instruction client preserves the synchronous Missions authority checkpoint at each native put/remove, and full session, connection and authority checks run again before the input dispatch.

MemoryService.sessionTitles resolves the native session's current authorized directory, checks the fresh preference and independently reads both safe scope projections. It rechecks session ownership and enablement after the reads. Unreadable scopes stay absent; missing folders supply empty title lists. Disabled memory reads its preference first, bypasses capability discovery and storage, and attempts removal of only codenomad.memory. Preparation failures and uncertain instruction puts also attempt removal of that key. Discovery, storage and instruction transport failures leave ordinary admission available; cancellation, retired connections and Missions authority fences remain blocking. Preparation, instruction publication and cleanup share a two-second advisory admission budget, including hung transports. Expiry cancels transport and fences late preparation continuations while preserving the caller's mandatory fences. An authenticated capability result of unsupported keeps the feature silent. When removal itself fails, the native session may retain its preceding entry until a later successful admission refresh; consumers must verify stored claims against current reality. Cleanup errors carry no memory content into logs.

The English instruction string always includes the recording rules, even when both lists are empty: corrections/preferences, successful unusual approaches, costly facts absent from code/docs, one fact per entry, saving before the final response with a one-sentence acknowledgement, and reference-only designation of an external memory. It directs the agent to read before acting and verify file and command claims. Title/type pairs travel as escaped JSON, with Unicode control and markup delimiters escaped, inside an 8,000 UTF-16-code-unit budget. Lexical sorting and round-robin scope selection make truncation stable; omittedTitles counts exclusions and the instructions direct the agent to list for all titles.

The native plugin awaits memory-context through the authenticated bridge before every prompt admission, including children outside the proxy. The bridge applies the same capability, ownership, preference and scope projection as direct sends. The hook shares the two-second memory budget across discovery, publication and cleanup. Tool cancellation propagates through ownership discovery and is checked again immediately before dispatch; admitted writes retain transaction recovery. Each activation owns and disposes its prompt hook with its tool registration. An explicit ownership refusal from every live backend clears the named entry and leaves unrelated native Locations usable. Missing/ambiguous backends and transport failures trigger the same best-effort named-entry cleanup and admit the prompt.

Preferences review, editing and badges

components/settings/agent-memory-settings-card.tsx mounts under General in both native Preferences and embedded Settings. The Memory switch reads and updates server.memoryEnabled (default false); the scope selector and editor are visible while enabled. The server keeps stored entries when disabled. Project context uses the shared Preferences resolver. Embedded Settings resolves the main window's active project and selected session Location on General demand; native Preferences keeps its explicit resolved context. Without an authorized project only About you can be selected. Titles/types/text have localized labels in all ten UI languages, and supplementary copy uses SettingsInfoTip. The cleanup action and its info tip wrap as one group. Editable title/text fields derive direction from their contents, and list titles use bidirectional isolation.

stores/agent-memory.ts owns demand reads, draft preservation, stale-response fencing and coalesced trailing invalidation after memory.changed or reconnect. Mutation replies check their context generation before changing drafts and only replace the draft version sent by that mutation, preserving newer edits. The list's scopeKey identifies the resolved namespace, and its server-generated observedAt is captured before the read. The entries sit in a settings-disclosure folded by default for the window's lifetime and unfolded by a dirty draft. Its summary shows the scope's count and limit (named Entries for assistive technology) and repeats the New, Modified and Needs review badges present in the list; rows render only while it is open. A successful read advances a monotonic localStorage consultation frontier per namespace while the list is open, or when it is unfolded after that read. Each visit freezes the previous frontier: created-after entries show New, otherwise updated-after entries show Modified. Badges remain visible through refreshes during that visit. Failed reads leave the saved frontier untouched; unavailable localStorage keeps the badges visit-local. The frontier belongs to the current UI storage origin.

The editor changes existing entries; Save and Forget send the displayed ID and revision, preserving agent session provenance. Forget requires an explicit confirmation. Cancel resets fields to the selected saved entry. Confirmation retains the entry ID, displayed revision and context lifetime: unchanged refreshes preserve consent, while a changed revision reports a conflict. Dirty drafts use the shared Settings leave guard; scope changes and cleanup confirmation also check it. Revision conflicts retain the draft and offer Reload, with confirmation before discarding edits. Flagged entries stay visible with Needs review, a contextual warning and editable content, while the server's safe projection excludes them from agent use. Read failures keep their explicit error, with retry; callers must never render them as empty scopes.

Cleanup sessions from Preferences

General's Memory scope bar offers Tidy up with an info tip and a short confirmation. It captures the resolved Preferences project directory and scope at the click, including for global memory. Project/scope changes revoke unsent confirmation. Empty, unreadable, disabled, flagged-only and non-writable scopes keep the action inactive. UI list snapshots carry cleanupWritable: under the repository lock the store checks Git's local branch, probes temporary-file creation/removal in the scope and Git publication directories, and opens existing entry/index/ref files for update without changing their contents. Probes leave entry bytes and commit history intact; normal writes retain their authoritative checks because filesystem permissions can change after a snapshot. Lists with a project context also return cleanupDirectory, the server-authorized execution-host directory, with ownership rechecked after the read. Cleanup compares the created session against this canonical directory, so WSL UNC requests match their Linux Location. A failed post-creation check keeps the session discoverable in the project's session inventory and shows the localized cleanup failure.

lib/native/memory-cleanup-command.ts defines the fixed scope/project/request-ID intent. Electron and Tauri accept it only from the trusted Preferences main frame, compare it to the host's current Preferences project, and forward to that window's exact local opener. Missing openers fail explicitly. The main renderer claims each Tauri event hint through the native host, which returns the pending intent only to its targeted local window and only once. The main renderer alone owns session creation, tab/session activation and the initial send through stores/agent-memory-cleanup.ts. Embedded Settings, including remote Electron and Tauri windows, use that same action directly; native forwarding belongs to the Preferences window. Request IDs use the shared UUID fallback on HTTP origins. The create call takes the captured explicit directory, independently of the currently selected conversation. Fresh enablement, readable safe entries, writability and project ownership are checked before the single creation attempt. Request IDs retain their result in the renderer (bounded to 256 admissions); uncertain outcomes keep the action disabled for that view and require inspection of project sessions before another deliberate attempt.

The fixed English prompt directs the model to read and verify each available entry against the project, merge duplicates, rewrite supported outdated claims through codenomad_memory, preserve unverifiable entries and external references, treat contents as untrusted data, and report created/modified/merged/deleted, unchanged and unverifiable entries. Only the selected scope may change.

Optional native instructions capability

memory/instructions-capability.ts reads the authenticated /openapi.json through the acquired connection and the bounded shared contract reader. It recognizes GET on /api/experimental/session/{sessionID}/instructions/entries, plus PUT and DELETE on that path's /{key} item. Recognition uses the API contract independently of the runtime version label.

Result Consumer policy
supported Admit memory integration after its other ownership and enablement checks.
unsupported Keep memory inactive silently and preserve the saved preference.
authentication Recover connection authentication; retain the preference.
unavailable Treat the current read as unavailable and requalify on later demand; retain the preference.

Only a valid authenticated OpenAPI document establishes absence. HTTP 401/403 are authentication failures. A discovery 404, transport failure, timeout, oversized response or malformed document is unavailable. Concurrent probes share one read per connection. Supported/unsupported results are retained with weak connection ownership; failures are released. A replacement connection qualifies anew, and every caller checks that its connection is still current before and after awaiting. The probe performs only a read.

Native child-session admission

Native children use the instruction synchronization contract above through an awaited ctx.session.hook("prompt", async event => …) registered during plugin setup. Use event.sessionID and await ctx.session.instructions.entry.put or remove before returning. Hooks run after Location plugin activation and before prompt inbox admission.

Preserve other instruction keys. Resolve each child's own server-authorized location rather than copying a parent's project identity or title list. Native synthetic/control inputs have their own admission paths; integrations using them must synchronize their named entry at their corresponding owned boundary.

The first model request includes the named entry in system instructions. Resumed sessions receive instruction changes as context-update notices at the next step boundary.

Validation

memory/integration.test.ts owns the serial real-Git/process suites in memory/*.integration.ts and server/routes/memory.integration.ts. The full server glob runs these cases in one process, with two explicitly ready workers for cross-process contention. The five committed entries, fresh locked decisions, Windows sharing failures and crash-recovery history remain asserted. Readiness and lock-candidate publication coordinate handoffs; test polling deadlines bound missing signals independently of the unchanged product lock deadline.

node --import tsx --test packages/ui/tests/contracts/agent-memory-types.test.ts
node --import tsx --test packages/server/src/memory/*.test.ts packages/server/src/forge/forge.test.ts
node --import tsx --test packages/server/src/memory/integration.test.ts packages/server/src/server/standalone-bridge.test.ts
npm run typecheck --workspace @neuralnomads/codenomad
node --import tsx scripts/test-memory-instructions-native.mjs <absolute-opencode-executable>
node --import tsx --test packages/server/src/opencode/memory/*.test.ts
node --import tsx --test packages/server/src/workspaces/session-memory-context.test.ts packages/server/src/server/__tests__/session-environment.test.ts packages/server/src/server/routes/mission-input.test.ts packages/server/src/server/routes/mission-lifecycle.test.ts packages/server/src/server/routes/mission-authority-checkpoint.test.ts
npm run build:memory --workspace @neuralnomads/codenomad
node --import tsx scripts/test-memory-tool-native.mjs <absolute-opencode-executable>
node --import tsx --test packages/ui/tests/browser/agent-memory.test.ts
npm run test:help
npm run build:help

Set CODENOMAD_MEMORY_TEST_WSL_DISTRO to a disposable-test-capable local distro and run node --import tsx --test --test-name-pattern="real WSL" packages/server/src/memory/integration.test.ts separately to include the real WSL Git/worktree test. The native instructions regression uses a private authenticated daemon, private home/configuration/database and a loopback synthetic provider. It checks session-local parent entries, first-call child instructions through the awaited hook, resumed-child updates, removal of only the memory key and independent mandatory admission refusal with an empty inbox. Its plugin bundle uses packages/server/scripts/native-plugin-build.mjs. The shipped-tool qualification also exercises the real bridge/store projection before a native child's first model call, title-only safe instructions, removal after disable while preserving another key, an unrelated native Location, and successful prompt admission with stale-key cleanup during a memory bridge outage. It also holds an accepted context request until the native hook's own budget admits the prompt, preserving other instruction owners.

Agent conventions

  • Keep entry validation, project identity, storage, session admission and UI projections in their own narrowly scoped modules.
  • Capacity and duplicate replacement are storage decisions; the shared limits and validation contract remain authoritative for every mutation entry point.
  • A missing storage folder represents an empty scope. Unreadable or malformed scope data must remain explicitly unavailable.
  • Never discover, read or import other agents' memory files automatically.