README.md

August 24, 2026 · View on GitHub

Never lose context. Never start over.

_{Beyond code, it remembers how your architecture evolves and how your engineering unfolds.}

npm package version

Make Every Interaction the Starting Point for the Next

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, DeepSeek Harness, and OpenCode 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.

Quick Start

Prepare Node.js 20+ (Node.js 24 LTS recommended) and at least one of Codex, Claude Code, DeepSeek Harness, or OpenCode. Python 3 is required for Repo Memory operations. Each coding-agent harness retains its own runtime requirements; current DeepSeek Harness releases require Node.js ^22.19.0 || >=24.0.0. DSH may be installed globally or initialized beforehand through its official npx workflow.

Install and Connect

1. Install the Package

npm install -g @memorax/memorax-code

2. Connect a MemoraX Account (Recommended)

Create a MemoraX account or use an existing one, then run:

memorax-code setup --existing-account

Tip

Using MemoraX Code across devices? Find the MemoraX username and API key needed by setup in the MemoraX Code configuration file on a configured device (normally ~/.memorax-code/config.toml), then enter them locally during setup on another device. This file contains your API key—keep it private and never paste it into chats or public issues.

Or Try Without an Account (90-Day Guest Mode)

To start immediately and connect an account later, run:

memorax-code setup

To activate your guest account, first run this command directly in your local terminal:

memorax-code account --show-mark-id

After obtaining the Mark ID, create your MemoraX account. 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.

Installation Troubleshooting

If the initial setup does not work as expected, check these common cases:

Symptom	Recommended fix
Installation fails with an unsupported Node.js version	Run `node --version` and upgrade to Node.js 20 or later before reinstalling MemoraX Code.
The package installed but setup did not start	This is expected. Run the appropriate setup command above from a normal interactive terminal.
Search, retrieval, or writeback is unavailable after setup	Run `memorax-code status` and `memorax-cli status`, then follow the detailed troubleshooting guide.

See Configuration for supported settings and Troubleshooting for detailed diagnostics.

Try Cross-Session Memory

Clone the example repository from the product website, then open Codex, Claude Code, DeepSeek Harness, or OpenCode in the project directory:

git clone https://github.com/SWE-agent/test-repo.git
cd test-repo

Invoke the Skill as $memorax-code in Codex or /memorax-code in Claude Code or DeepSeek Harness. In OpenCode, ask the agent to use the memorax-code skill by name. The prompts below use its product name and work in all four 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.

Four Clear Memory Boundaries

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 stay in the current repository under .repo_memory/. 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.

Product Capabilities

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.
Background Repo Memory maintenance	Automatically organizes repository structure, entry points, and history evidence in the background, then updates them according to policy to reduce repeated searching and summarization.
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, DeepSeek Harness, and OpenCode to trigger memory retrieval, reminders, and writeback. Automatic quota reminders are currently available in Codex, Claude Code, and OpenCode.

Your Memory, Your Control

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. Automatic retrieval remains off until explicitly enabled.

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.

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 for extraction and storage. It does not upload the complete retained client trace artifact or local trace path.

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.

Update

For a global npm installation:

memorax-code update

The command follows the installed release channel and preserves configuration. Restart or refresh Codex, Claude Code, DeepSeek Harness, and OpenCode when a release changes installed integration assets.

Windows Upgrade Note

If you are upgrading MemoraX Code v0.1.3-v0.1.6 to v0.1.7 on Windows, run:

memorax-code stop
memorax-code update --latest
memorax-code

This one-time step is not required for later upgrades.

Uninstall

Run the product lifecycle before removing the npm package:

memorax-code uninstall

This removes managed integrations and the global package while retaining MEMORAX_CODE_HOME (default ~/.memorax-code), Claude plugin data, provider configuration, and memories stored in MemoraX. Remove retained local or cloud data separately only after reviewing what you still need.