Beyond code, it remembers how your architecture evolves and how your engineering unfolds.
English · 简体中文
Coding agents are good at the task in front of them, but a new session often starts without the architecture, failed attempts, repository rules, or working preferences established before it.
MemoraX Code gives Codex, Claude Code, CodeBuddy CLI, WorkBuddy, DeepSeek Harness, OpenCode, Trae, and Cursor a shared memory layer for that context. It can recall prior engineering knowledge, capture reusable lessons from completed work, maintain repository knowledge, and carry your procedures and preferences into future sessions.
The goal is not to remember everything. It is to bring back the small amount of memory relevant to the current task so the agent can reach useful investigation and validation sooner.
Prepare Node.js 20+ (Node.js 24 LTS recommended) and at least one of Codex, Claude Code, CodeBuddy CLI, WorkBuddy, DeepSeek Harness, OpenCode, Trae, or Cursor.
For DeepSeek Harness (DSH), current releases require Node.js
^22.19.0 || >=24.0.0. Install or initialize DSH first, create at least one
Profile, and ensure pnpm is on PATH before running setup. MemoraX Code
does not install or update DSH.
On Linux, guest credentials require /usr/bin/secret-tool from
libsecret and an available Secret Service in the current user session. For
Remote SSH, WSL, or Dev Containers, install MemoraX Code in the same environment
as the coding agent. MemoraX search and writeback require network access.
npm install -g @memorax/memorax-codeThis installs the package; it does not start interactive setup. Do not use
--ignore-scripts: npm lifecycle scripts safely stop and restore an existing
running managed Backend during package replacement.
Create a MemoraX account or use an existing one, then run from a normal interactive terminal:
memorax-code setup --existing-accountFollow the setup prompts to enter your MemoraX username and API key locally.
For a coding agent without an interactive terminal, pass the API key through
stdin. The examples assume MEMORAX_SETUP_API_KEY is already provided by the
caller. Do not put the key in command arguments or project files.
printf '%s\n' "$MEMORAX_SETUP_API_KEY" | memorax-code setup --existing-account --non-interactiveIn Windows PowerShell:
$env:MEMORAX_SETUP_API_KEY | memorax-code.cmd setup --existing-account --non-interactiveThis explicit command replaces the saved key and uses the detected local
username and system language. It reports API Key match: true after local
configuration and readiness checks; this does not verify cloud credentials.
See non-interactive setup
for input and reuse behavior.
Tip
Using MemoraX Code across devices? Find the username and API key in the
configuration file on a configured device (normally
~/.memorax-code/config.toml), then enter them in the local setup terminal
on the new device. This file contains your API key; keep it private and
never paste it into chats or public issues.
To start immediately and connect an account later, run:
memorax-code setupDefault setup reuses a complete existing connection. Otherwise, it detects
your local username and language, asks when needed, and creates or restores
guest credentials. To replace the saved connection, use
memorax-code setup --reconfigure for guest mode or
memorax-code setup --existing-account for a registered account.
To keep your guest memory when registering later, first run this command directly in your local terminal:
memorax-code account --show-mark-idImportant
Obtain the Mark ID before registering, then use it to activate your guest account on MemoraX. The platform does not currently support attaching a Mark ID to an account that has already been registered.
Both setup paths automatically detect supported coding agents. Restart or refresh every detected coding agent after setup.
| Client | Complete activation |
|---|---|
| Codex | Enable MemoraX Code Codex Adapter from Plugins or /plugins if it is not already enabled. |
| Claude Code | Restart or refresh the client to load the managed plugin and Hooks. |
| CodeBuddy CLI | Start a new CLI session to load the managed plugin, Hooks, and Skill. |
| WorkBuddy | Restart WorkBuddy to load its independently managed plugin, Hooks, and Skill. |
| DeepSeek Harness | Restart or refresh DSH to load the plugin registered in existing Profiles. |
| OpenCode | Restart or refresh the client to discover the managed plugin and Skill. |
| Trae | In Settings → Hooks → Global → Configured Hooks, enable the registered Global Hooks once. Setup installs the Hooks and Skill; this switch requires manual activation. |
| Cursor | Restart or refresh Cursor, then open a new conversation to load its native user Hooks, shared Skill, and managed background subagent. |
Cursor installs independently of Claude Code under ~/.cursor/hooks.json and
~/.cursor/skills/memorax-code/; setup preserves its third-party integration
setting. Use the Skill for CLI Search and manual Add. Automatic Add reads verified
native database turns and requires Node.js 22.13+
with built-in SQLite (Node.js 24 recommended). It supports ordinary prompts,
edited resends, and continuations bound to an observed preceding turn; interrupted
or ambiguously correlated content is skipped. Prompt Hooks inject trusted User
Profile preferences on the first eligible turn and Procedure Memory on the
configured reminder cadence. The default Procedure cadence is turns 1, 6, and
11 (then every five turns). After a recorded compaction is verified against the
native database, the next nonempty, registered prompt restores Profile and
personal reminders; Procedure keeps its normal cadence. Missing evidence skips
recovery, and restoration during the same continuing task is not guaranteed.
Repo Memory initial builds and policy-based maintenance use Cursor's native
background subagent; no separate Cursor CLI or
CLI login is required. Cursor may request normal tool approvals. See
Cursor configuration.
Open a project, start a new client session, and send one prompt. Then run these commands from the project directory:
memorax-code --version
memorax-code status
memorax-cli statusIn Windows PowerShell, use memorax-cli.cmd status. A configured integration
may still report hook-runtime=unverified until the client executes its Hook.
After a Hook executes successfully, that client's Hook runtime should change
to observed.
memorax-code status checks the local Backend and client integrations;
memorax-cli status checks the local memory configuration and workspace scope.
Neither command sends a test request to MemoraX. A real search or write verifies
remote connectivity and credentials; follow the cross-session example below.
For client-specific diagnostic commands, see
Troubleshooting.
Package installation does not launch setup automatically; run one of the setup commands above, using stdin mode when an agent has no interactive terminal. For incomplete setup or unavailable memory, start with the status commands and follow Troubleshooting.
Both commands are included in the same package. Follow the Windows PATH repair steps to bootstrap setup or repair a stale terminal environment.
Clone the example repository from the product website, then open Codex, Claude Code, CodeBuddy CLI, WorkBuddy, DeepSeek Harness, OpenCode, Trae, or Cursor in the project directory:
git clone https://github.com/SWE-agent/test-repo.git
cd test-repoInvoke the Skill as $memorax-code in Codex or /memorax-code in Claude Code
or DeepSeek Harness. In OpenCode, CodeBuddy CLI, WorkBuddy, Trae, or Cursor, ask the agent
to use the memorax-code skill by name. The prompts below use its product name
and work in all supported clients.
Send these prompts in order in the same session:
- Use the MemoraX Code skill to build Repo Memory, retrieving only the latest 3 issues, pull requests, and commits.
- Review the recent Repo Memory issue: the zeroth number was once calculated incorrectly. Avoid repeating the same problem now.
- Use the MemoraX Code skill to remember the engineering lesson from this coding task.
Close the current conversation, start a new session in the same repository, and send:
Use the MemoraX Code skill to recall the earlier engineering lesson and suggest what to check.
The agent should retrieve the saved lesson and use it to make suggestions for the current repository.
Tip
The prompts above are only for quick verification. In normal use, you do not
need to invoke the MemoraX Code skill to add memory manually. It writes
relevant memory in the background and guides agents to search when useful.
Local activity and status are retained as content-controlled trace and reconciliation records under MEMORAX_CODE_HOME.
| Memory | The question it answers | Examples |
|---|---|---|
| Coding Memory | What engineering lessons should carry into the next task? | Verified fixes, failed approaches, design rationale, pitfalls, and regression checks |
| Repo Memory | What should an agent know about this repository? | Architecture maps, module ownership, entry points, and commit/PR/MR/issue evidence |
| Personal Memory | How should the agent communicate and collaborate with you? | User Profile preferences such as language, tone, explanation depth, and result format |
| Procedure Memory | How should this kind of task be carried out? | Reusable steps, checklists, prerequisites, exceptions, and validation gates |
Personal Memory and Procedure Memory are global to the user under
$MEMORAX_CODE_HOME/personal-memory/ (default ~/.memorax-code/personal-memory/): User Profile
uses user-profile/preferences.md, and each Procedure topic uses its own file
under procedure-memory/. Applicability may mention a repository, tool, or
workflow, but no personal-memory layer exists inside a repository. Existing
.repo_memory personal-memory files are ignored and are not migrated. A
durable User Profile preference may be saved implicitly; Procedure Memory is
saved only when the user explicitly asks. When saved content already exists,
MemoraX Code compares its meaning before writing: an equivalent request makes
no change; a durable refinement or conflict updates the matching entry and
removes the superseded wording; an invalid scope is corrected, or the entry is
deleted only when it is wholly obsolete. An explicit forget request deletes
only the named preference, procedure topic, section, or step and leaves
unrelated memory unchanged. One-time task instructions do not change saved
memory, and the Agent asks before writing when the durable intent or target is
unclear.
| Capability | What it does |
|---|---|
| Background memory writeback | Extracts reusable knowledge from completed turns and writes it to Coding Memory in the background. |
| Preference continuity | Records User Profile preferences and injects them into future tasks on a configured cadence. |
| Procedure reuse | Records reusable task procedures and reminds future agents to apply them. |
| Visible memory impact | In Codex, Claude Code, CodeBuddy CLI, WorkBuddy, DeepSeek Harness, OpenCode, Trae, and Cursor, opens the final answer with a brief natural-language note when an explicit Coding Memory Search or a Repo, Procedure, or Profile Memory available to the current turn materially guided the task. |
| Background Repo Memory maintenance | Automatically organizes repository structure, entry points, and history evidence in supported clients, then updates them according to policy to reduce repeated searching and summarization. Trae remains Skill-only; Cursor uses its native background subagent for initial builds and maintenance. |
| Active memory control | Lets you search and add memory through the bundled MemoraX Code skill or the CLI. |
| Client integration | Integrates with Codex, Claude Code, CodeBuddy CLI, WorkBuddy, DeepSeek Harness, OpenCode, Trae, and Cursor for Skill-driven Search, local reminders, and automatic writeback. Automatic quota reminders are currently available in Codex, Claude Code, CodeBuddy CLI, WorkBuddy, OpenCode, and Trae. |
| Local observability | Uses content-controlled local trace and reconciliation records to inspect activity counts, retrieval, and writeback status. |
MemoraX is required for cloud-backed memory. Completing setup activates MemoraX search/add and the generated configuration's automatic writeback; there is no second writeback confirmation. Search runs when the agent uses the Skill or you invoke the CLI. Hooks provide local memory context and reminders without issuing Search requests.
Optional Jev configuration
lets a separate TypeSafe model judge each eligible distinct user request. When
Search is useful, the agent reads the memorax-code Skill's Search reference
and follows its query and execution guidance. It sends bounded current-request
and previous-turn text to TypeSafe, uses your Jev key, and is disabled by default.
Failures fall back to the normal Skill reminder cadence; the agent still
executes Search.
Local trace capture is enabled by default for supported clients. Depending on
client capabilities, retained traces under MEMORAX_CODE_HOME may contain
prompts, responses, recalled memory, reminder text, and local paths. Use the
local trace settings to switch to
metadata-only capture or disable a client's trace.
Minimal local session state remains when trace is disabled so memory operations
keep the correct workspace scope.
Failures in setup, explicit Search/Add, Backend start/stop/restart, client
deployment, and package updates provide an error code, recovery guidance, and a
local content-free diagnostic; see failure recovery.
Hook execution and automatic writeback also retain known failures locally with
Debug off, without adding messages to the conversation or blocking the coding task.
memorax-code status summarizes recent failures; use memorax-code logs --diagnostics
or memorax-code logs --id <diagnostic-id> for details you can review and share.
Coding Memory follows the repository or workspace. Recognized default chat
directories or contexts in Codex, WorkBuddy, OpenCode, and Cursor share General under the
same configured MemoraX user ID. A Cursor conversation with no folder selected
uses this shared @General scope; opening a repository uses that repository's
normal scope. Existing memories are not migrated; see
memory scope for the directory rules.
Guest quota reminders may display the complete Mark ID. Treat reminder text and retained traces containing it as sensitive.
Active memory operations send their query or selected content to MemoraX. Automatic writeback sends selected user instructions and the matching final Agent response from trusted workspace turns after removing the final-answer memory-impact disclosure, then extracts and stores reusable memory. It does not upload the complete retained client trace artifact or local trace path.
QA writeback preserves available native timestamps and labels observation-time fallbacks; see message timestamps.
Sign in to MemoraX Console at any time to view, edit, or delete saved memories. MemoraX Cloud does not receive model-provider credentials or local Backend tokens.
Read Configuration for all settings and Security for network, local-data, and retention boundaries.
For a global npm installation:
memorax-code updateSetup also enables background updates while the managed Backend is running.
An update briefly stops a running managed Backend and restores it with the
retained client selection.
See update settings
for release channels, custom state roots, client selection, Backend restoration,
and disabling background checks. Restart or refresh a client after an update
changes integration assets it has already loaded.
If package replacement fails, follow the update recovery steps
for memorax-code update --recover.
For older Windows installations that fail with an EBUSY rename error, follow
the legacy upgrade recovery.
Run the product lifecycle before removing the npm package:
memorax-code uninstallThis removes managed integrations and the global package while retaining
configuration and stored memories. Do not run npm uninstall -g first: it can
remove the product command before client integration cleanup runs. See
Uninstall and Retention for the complete
retained-data list.
After a complete uninstall and reinstall, run memorax-code setup again;
default setup reuses a complete retained connection. A normal
memorax-code stop or partial client uninstall preserves setup completion.
Issues and pull requests are welcome. Read CONTRIBUTING.md before making a change, and never include API keys, raw transcripts, private memory, or local trace artifacts in a public report.
MemoraX Code is available under the MIT License.