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) andproject(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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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.
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.
- 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.