# MemoraX Code: a shared memory layer for Codex, Claude Code and other coding agents

> MemoraX Code stores engineering experience, repository knowledge and working preferences so a new agent session does not start from zero. It installs from npm, needs Node.js 20 or newer, and supports seven coding clients.

**memorax-ai/memorax-code** — A memory plugin for AI coding that turns engineering experience, repository knowledge, and your way of working into memory that remains useful in future tasks.

- Repository: https://github.com/memorax-ai/memorax-code
- Website: https://code.memorax.net/
- Stars: 2,015 · Forks: 68
- Language: JavaScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/memorax-ai-memorax-code

## The session reset problem MemoraX Code targets

A coding agent is good at the task in front of it and forgetful about everything behind it. The README puts the failure plainly: a new session often starts without the architecture, the failed attempts, the repository rules, or the working preferences that were established before it. The agent then spends its first turns rediscovering facts the previous session already knew.

MemoraX Code is aimed at developers who switch between agents and expect continuity across them. The README lists Codex, Claude Code, CodeBuddy CLI, WorkBuddy, DeepSeek Harness, OpenCode, and Trae as supported clients, and describes the product as a shared memory layer for that context. That word shared matters: the same memory is meant to serve whichever client you open next, rather than being trapped inside one vendor's session store.

The project is explicit that recall is selective. The stated goal is not to remember everything, but to bring back the small amount of memory relevant to the current task so the agent reaches useful investigation and validation sooner. That is a deliberate design constraint rather than a marketing line, and it shapes how the system is built.

## How the Backend, adapters and Hooks fit together

The repository layout shows the architecture directly. Under packages/ts there are separate packages for the backend and for each client integration: memorax-code-backend, memorax-code-adapter-common, memorax-code-codex-adapter, memorax-code-claude-adapter, memorax-code-dsh-adapter, memorax-code-opencode-adapter, memorax-code-codebuddy-adapter, and memorax-code-trae-adapter. A common adapter package sits underneath the client-specific ones, which suggests shared transport and lifecycle code with thin per-client layers on top.

The Makefile confirms this split. Its test-ts target typechecks and tests the backend, then calls test-adapter-common, test-shared-skill, and one test target per adapter. There is also a shared-skill test suite at test/shared-skill, and the README refers to a Skill installed alongside plugins and Hooks for several clients. So the integration surface is not just a plugin: for CodeBuddy CLI, WorkBuddy, OpenCode, and Trae the setup installs a plugin, Hooks, and a Skill.

The runtime picture is a local Backend process plus per-client Hooks. The README says the npm lifecycle scripts safely stop and restore an existing running managed Backend during package replacement, which tells you the Backend is managed by the package rather than started by hand. Searches and writebacks go out to MemoraX over the network, so memory is not purely local. That is the central trade-off of the design: a local process for orchestration, a remote service for storage and retrieval.

## Installing MemoraX Code and running a first session

The README requires Node.js 20 or newer, with Node.js 24 LTS recommended, plus at least one supported coding agent. Install the package globally:

```bash
npm install -g @memorax/memorax-code
```

This installs the package but does not start interactive setup. The README warns against --ignore-scripts, because the npm lifecycle scripts stop and restore an existing running managed Backend during package replacement.

Next, connect an account. The recommended path is to create a MemoraX account, then run setup from a normal interactive terminal:

```bash
memorax-code setup --existing-account
```

The prompts ask for your MemoraX username and API key locally. If you want to start before registering, plain setup creates guest credentials with a 90-day guest mode, and you can connect an account later. To replace a saved connection, use memorax-code setup --reconfigure for guest mode or memorax-code setup --existing-account for a registered account.

If you begin as a guest and later register, run this in your local terminal first:

```bash
memorax-code account --show-mark-id
```

The README is explicit that the Mark ID must be obtained before registering and then used to activate the guest account on the MemoraX platform. The platform does not currently support attaching a Mark ID to an account that has already been registered, so the order is not optional.

After setup, restart or refresh every detected client. Activation differs per client. Codex needs the MemoraX Code Codex Adapter enabled from Plugins or /plugins if it is not already on. Claude Code, CodeBuddy CLI, WorkBuddy, DeepSeek Harness, and OpenCode need a restart or refresh. Trae is the odd one: in Settings, Hooks, Global, Configured Hooks, you must enable the registered Global Hooks once by hand, because setup installs them but does not switch them on.

Then open a project, start a new session, send one prompt, and run the checks from the project directory:

```bash
memorax-code --version
memorax-code status
memorax-cli status
```

On Windows PowerShell, the second CLI is invoked as memorax-cli.cmd status. The two status commands check different things: memorax-code status covers the local Backend and client integrations, while memorax-cli status covers local memory configuration and workspace scope. Neither sends a test request to MemoraX, so a green status does not prove your credentials work. A configured integration may report hook-runtime=unverified until the client actually executes its Hook; after a successful execution that client's Hook runtime should read observed. Only a real search or write verifies remote connectivity.

## Where the setup breaks: Linux secrets, SSH, and DSH prerequisites

Several constraints in the README are easy to skim past and expensive to hit later. On Linux, setup-managed credentials require /usr/bin/secret-tool from libsecret and an available Secret Service in the current user session. A headless server or a session without a Secret Service will not satisfy that, and the README does not describe a fallback for storing credentials without it.

The second constraint concerns where you install. For Remote SSH, WSL, or Dev Containers, MemoraX Code must be installed in the same environment as the coding agent. Installing the CLI on your laptop while the agent runs in a container puts the Backend and the Hooks in different places. The README does not document a supported split arrangement.

DeepSeek Harness has its own prerequisites. Current DSH releases require Node.js ^22.19.0 or >=24.0.0, so the general Node.js 20 floor is not enough for that client. You must install or initialize DSH first, create at least one Profile, and have pnpm on PATH before running setup. MemoraX Code does not install or update DSH.

Network access is also required for search and writeback. If your team works in an air-gapped environment, the memory layer cannot retrieve or persist anything, and the local Backend alone will not help.

## What MemoraX Code is not the right tool for

The clearest limitation is client coverage. Setup automatically detects supported coding agents, and the list is seven clients. If your editor or agent is not among Codex, Claude Code, CodeBuddy CLI, WorkBuddy, DeepSeek Harness, OpenCode, and Trae, there is no documented integration path. The presence of a common adapter package suggests the architecture could accommodate more, but the README does not describe a public adapter API or a plugin authoring guide, so treating that as an extension point is speculation rather than a plan.

The second limitation is the dependency on a remote service for the parts that matter most. Status checks are local, but retrieval and writeback need network access and valid credentials. A developer who wants memory that never leaves the machine is looking at the wrong shape of tool, regardless of how the local Backend is packaged.

The third is verification friction. Because neither status command sends a test request, and because hook-runtime stays at unverified until a Hook actually fires, a fresh install can look healthy while nothing is connected. You have to open a project, send a prompt, and re-check before you know the integration is live. That is a reasonable design, but it means the first-run experience has a step that cannot be automated away.

Finally, the guest mode has a hard boundary worth stating: the Mark ID must be captured before registration. Anyone who registers first and then tries to attach guest memory is told by the README that the platform does not currently support it.

## How it compares with agent-native memory features

The obvious alternative is whatever memory your agent already ships. Claude Code has its own context and project instruction mechanisms, and the repository itself carries CLAUDE.md and AGENTS.md at the top level, which is the conventional way to hand repository rules to an agent. Those files are static: you write them, they are read at session start, and they do not learn from completed work.

MemoraX Code takes a different approach on two axes. First, it captures lessons from finished work rather than only replaying what a human wrote down, which the README describes as capturing reusable lessons from completed work. Second, it spans clients, so the same memory is available whether you open Codex or Claude Code next. A CLAUDE.md file does neither.

The cost of that difference is operational. A checked-in instruction file has no Backend, no credentials, no network dependency, and no per-client activation step. MemoraX Code has all four. If your team standardizes on a single agent and is satisfied with hand-written project instructions, the added machinery buys you little. If you rotate between agents, or you keep re-explaining the same architecture decisions, the shared layer is addressing a real gap that static files do not cover.

## Licence, maintenance and upgrade cost

MemoraX Code is MIT licensed, so you can read, modify, and redistribute the source under those terms. The licence covers the code in this repository. It does not cover the MemoraX hosted service that search and writeback depend on, and the README does not state terms for that service, so the licence question and the service question are separate. Nothing here is legal advice; if you need to redistribute the package inside a product, read the LICENSE file and the platform terms yourself.

On maintenance, the last push to the default branch was on 2026-09-10, and the most recent releases are v0.1.16 on 2026-09-10, v0.1.15 on 2026-09-09, and v0.1.14 on 2026-09-07. The repository is not archived. The version numbers are all 0.1.x, which tells you the project presents itself as pre-1.0 and the API surface may still move.

Upgrade cost is shaped by two things the README calls out. First, the npm lifecycle scripts stop and restore a running managed Backend during package replacement, so upgrades are handled rather than manual, but you should not bypass them with --ignore-scripts. Second, every client integration must be re-verified after an upgrade, because activation differs per client and Trae requires a manual Global Hooks toggle. Budget for a prompt-and-check cycle per client, not just an npm install.

## Conclusion

Adopt MemoraX Code if you run several supported coding agents against the same repositories and want prior investigation, repository rules and preferences available in new sessions. Skip it if you work offline, cannot run a local Backend, or use a client outside the seven supported ones, since setup only detects those. Before rolling it out, verify that the Backend starts and that each client's hook runtime moves from hook-runtime=unverified to observed after you send a prompt, because status reports alone do not prove the integration works.

## FAQ

### Which coding agents does MemoraX Code support?

The README lists Codex, Claude Code, CodeBuddy CLI, WorkBuddy, DeepSeek Harness, OpenCode, and Trae. Setup automatically detects supported agents among those. Activation differs per client, and Trae requires you to enable the registered Global Hooks manually.

### What Node.js version does MemoraX Code need?

The README requires Node.js 20 or newer, with Node.js 24 LTS recommended. DeepSeek Harness is an exception: current DSH releases require Node.js ^22.19.0 or >=24.0.0.

### Can I use MemoraX Code without creating an account?

Yes. Running memorax-code setup without flags creates or restores guest credentials in a 90-day guest mode, and you can connect an account later. To keep guest memory when you register, run memorax-code account --show-mark-id first, because the platform does not currently support attaching a Mark ID to an already registered account.

### Does memorax-code status prove that MemoraX Code is connected?

No. The README states that neither memorax-code status nor memorax-cli status sends a test request to MemoraX. A real search or write verifies remote connectivity and credentials, and a client's Hook runtime stays at hook-runtime=unverified until that client executes its Hook.

### Where is the MemoraX Code configuration file stored?

The README refers to the configuration file on a configured device as normally ~/.memorax-code/config.toml. It contains your API key, so the README says to keep it private and never paste it into chats or public issues.

## Sources

- [License: MIT](https://github.com/memorax-ai/memorax-code/blob/main/LICENSE)
- [memorax-ai/memorax-code on GitHub](https://github.com/memorax-ai/memorax-code)
- [Project website](https://code.memorax.net/)
- [README](https://github.com/memorax-ai/memorax-code/blob/main/README.md)
- [Releases](https://github.com/memorax-ai/memorax-code/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/memorax-ai-memorax-code