Development Guide

July 28, 2026 · View on GitHub

This guide is for contributors working on Memorix itself.

Memorix is a TypeScript project built around:

MCP server runtime
memcode bundled terminal-agent runtime
CLI workflows
SQLite canonical persistence with compatibility/fallback layers
Orama search
dashboard and HTTP service

Current Development Baseline

The current release work targets the 1.1 line while package metadata may still show the last published patch version until the release commit is cut.

Contributors should assume the following areas are part of the 1.1 release line:

shared memory across MCP clients, CLI, SDK, dashboard, hooks, and memcode
memcode uses Memorix project memory, hooks, /memory commands, resumable sessions, and model switching as the bundled terminal agent
TOML-first configuration with global ~/.memorix/config.toml and project <git-root>/memorix.toml
separate [agent], [memory.llm], and [embedding] model lanes
privacy-safe handoff receipts and doctor receipt diagnostics
optional session semantics in generated agent rules
notify-only auto-update by default with explicit install opt-in
dashboard config loading aligned with CLI/TUI status surfaces
the existing layered retrieval, retention, attribution, and compact output model

1. Prerequisites

Node.js >=22.18.0
npm
Git

Clone and install:

git clone https://github.com/AVIDS2/memorix.git
cd memorix
npm install

Optional local dependencies:

fastembed for local embedding experiments
@huggingface/transformers for transformer embedding mode

Memorix still works without them.

2. Core Commands

Build

npm run build

Watch mode

npm run dev

Full test suite

npm test

Vitest watch mode

npm run test:watch

Local runtime checks

memorix serve
memorix background start
memorix status

3. Recommended Development Loop

For most feature work:

write or update a focused test
implement the change
run the targeted test file
run npm run lint
run npm run build
run npm test
validate the real MCP or CLI path if the feature affects runtime behavior

Examples:

npx vitest run tests/git/noise-filter.test.ts
npm run lint
npm run build
npm test

If the feature touches the dashboard, HTTP transport, or MCP wiring, do a live verification after the test suite.

4. Repository Structure

High-level layout:

src/
  cli/                 interactive menu and subcommands
  compact/             compact formatting and token budgeting
  config/              TOML-first config, dotenv/YAML compatibility, provenance
  dashboard/           dashboard server and static frontend
  embedding/           embedding providers
  git/                 Git Memory extractor, hook path, noise filter
  hooks/               IDE hook normalization and capture
  llm/                 optional LLM quality helpers
  memory/              observations, sessions, retention, graph, formation
  project/             Git-based project detection and aliases
  rules/               rules sync across agents
  search/              intent-aware retrieval helpers
  skills/              memory-driven skills generation
  store/               Orama index and persistence
  team/                orchestration coordination registry, tasks, locks, messages
  workspace/           MCP and workflow sync across agents

tests/
  ...mirrors runtime modules with focused unit and integration tests

Docs layout:

README.md: landing page and quick start
docs/SETUP.md: client setup and troubleshooting
docs/CONFIGURATION.md: TOML-first config and legacy compatibility
docs/MEMCODE.md: bundled terminal-agent guide
docs/GIT_MEMORY.md: Git Memory workflows
docs/ARCHITECTURE.md: system design
docs/API_REFERENCE.md: MCP tool surface

5. Runtime Modes to Validate

stdio MCP

memorix serve

Use this to validate:

tool registration
stdio MCP behavior
IDE integration compatibility

HTTP MCP + dashboard

memorix background start

Use this to validate:

HTTP MCP endpoint
Team tools
dashboard API parity
dashboard UX

Use memorix serve-http --port 3211 when you want the same stack in the foreground for debugging, manual supervision, or custom ports.

Dashboard-only mode

memorix dashboard

Useful for local UI checks. The HTTP service also serves the embedded dashboard used in normal background mode.

6. Feature Areas Worth Testing Live

Some features deserve real runtime verification, not just tests:

project identity detection
config provenance
Git hook installation and post-commit ingest
cross-project search and detail refs
HTTP transport and Team tools
dashboard graph stability and page layout

When validating these, prefer:

real MCP calls
real CLI commands
real temporary Git repositories

over only unit tests.

7. Git Memory Development Notes

Git Memory turns commit history into searchable engineering memory, so changes here directly affect how well agents can recall what changed in a codebase.

When working in this area, validate:

memorix git-hook --force
memorix git-hook-uninstall
memorix ingest commit
memorix ingest commit --force
memorix ingest log --count N

Also validate behavior in:

normal repositories
worktrees
noisy commit streams

See GIT_MEMORY.md for user-facing behavior.

8. Configuration Development Notes

Memorix uses TOML as the primary user-facing config model:

global ~/.memorix/config.toml
project <git-root>/memorix.toml

When touching config code, always validate:

project memorix.toml
global ~/.memorix/config.toml
project .env
user ~/.memorix/.env
legacy project/user memorix.yml
legacy ~/.memorix/config.json
env var overrides

And always check:

memorix status

to make sure provenance diagnostics match runtime behavior.

The repository's canonical workflow is Memorix release. It is the versioned source for agents and maintainers; its checks supplement, rather than replace, the explicit maintainer approval required to publish.

Recommended release flow:

update docs and version metadata
run:

npm run lint
npm run build
npm test

Model catalog refresh is a separate maintenance step, not part of the release build. Run it only when intentionally updating generated provider snapshots:

npm run update-models
git diff -- packages/ai/src/models.generated.ts packages/ai/src/image-models.generated.ts

The generators refuse unexpectedly shrunken live results by default. If a shrink is intentional after reviewing the diff, rerun with MEMORIX_ALLOW_MODEL_CATALOG_SHRINK=1.

validate key live flows:

MCP store/search/detail
dashboard
Git Memory
config diagnostics
memorix setup --agent codex --global followed by memorix doctor agents --agent codex --scope global --json in an isolated home, when changing the Codex integration

inspect package contents:

npm pack --dry-run --json

commit and push
publish the supported public package manually when ready:

npm publish --access public

Notes:

prepublishOnly synchronizes and checks Registry metadata, then runs build + test; it does not contact live model catalog APIs
server.json is the official MCP Registry record. Keep it synchronized with package.json by running npm run sync:mcp-registry; verify it with npm run check:mcp-registry before a release.
The GitHub publish workflow publishes npm first, then uses GitHub OIDC to publish the same verified version to the official MCP Registry. It does not require a Registry token or private key in repository secrets.
@memorix/ai, @memorix/agent-core, @memorix/tui, and @memorix/memcode are internal workspaces. Their code is bundled into the root memorix distribution and they must stay private unless the project deliberately establishes an owned npm scope and a separate package-support contract.
npm publish is usually manual, especially when 2FA is enabled
GitHub release automation should not be treated as a substitute for manual runtime validation

10. Contribution Standards

When contributing to Memorix:

keep public docs aligned with runtime behavior
prefer explicit, project-safe behavior over clever fallback
avoid adding features without a clear product story
validate MCP behavior with real calls when changing server logic
keep Git Memory, reasoning memory, and retrieval semantics coherent

Memorix is strongest when its engineering truth layer, reasoning layer, and local service runtime all stay in sync.