# nyxilum-memory-mcp

**Detail memory for long AI-coding sessions.** An MCP server written in pure
[NyxilumLang](https://github.com/Faneraiy14/NyxilumLang) (`.nx`) that stores the things a new session
loses: *why* a choice was made, what was tried and rejected, side findings, non-obvious nuances — and
pulls back only what the **current task** needs.

| Store | Holds |
|---|---|
| Architecture docs | WHAT exists (state, stack, structure) |
| Claude Code `memory/` | who the user is, working rules, short facts |
| **this** | WHY: decisions + reasons, rejected options, findings, nuances |

## How it works
- One record = one Markdown file, `records/<project>/<id>.md`, **never rewritten**.
- State (archived, recall counters) = replay of an append-only `events.jsonl`.
- `recall(task, project)` — own scoring (tokenize → prefix "stem" → IDF → weights tag×3 / title×2 / body×1,
  project bonus, hit boost, noise threshold). Returns a *short* list within a character budget;
  `get(ids)` returns full text only for what you need.
- Cleaning: `review_old` reports candidates with reasons (not recalled for N days, repo changed a lot
  since, linked file vanished). `archive` is reversible and needs `user_confirmed`. `purge` (physical
  delete, archived only) is two-step: `purge_request` returns a one-time phrase the **human** must type
  exactly; `purge_confirm` compares it character by character (a wrong try = refusal + new phrase).
- Hooks: `SessionStart` injects a tiny digest (counts + recent titles for the current project);
  `Stop` nudges (non-blocking) when many turns passed without `remember`.

Tools: `remember` `recall` `get` `list` `handoff` `review_old` `archive` `unarchive` `purge_request` `purge_confirm`.

## Install
Needs the `nx` binary ([NyxilumNode releases](https://github.com/Faneraiy14/NyxilumNode/releases)) on disk.
```bash
git clone https://github.com/Faneraiy14/nyxilum-memory-mcp
claude mcp add nyxilum-memory -s user -- /path/to/nx /path/to/nyxilum-memory-mcp/server.nx
```
Hooks (optional) — add to `~/.claude/settings.json`, exec form (no shell):
```json
{"hooks":{
 "SessionStart":[{"hooks":[{"type":"command","command":"/path/to/nx","args":["/path/to/nyxilum-memory-mcp/hooks/hook.nx","SessionStart"],"timeout":15}]}],
 "Stop":[{"hooks":[{"type":"command","command":"/path/to/nx","args":["/path/to/nyxilum-memory-mcp/hooks/hook.nx","Stop"],"timeout":15}]}]}}
```
Hooks stay silent until the data folder exists (opt-in).

## Configure
| Env | Default | Meaning |
|---|---|---|
| `NX_DETAILS_DIR` | `~/.claude/details` | where data lives |
| `NX_PROJECTS_ROOT` | `~/Projects` | where your repos are (project detection, "repo changed" check) |

`<data dir>/config.json` overrides any key: `stemLength`, `stopWords`, `weightTag/Title/Body`,
`projectBonus`, `hitBoost`, `minScore`, `defaultLimit`, `defaultMaxChars`, `staleDaysNoRecall`,
`staleDaysFinding`, `staleCommits`, `purgePhraseMinutes`, `dupScore`, `reminderTurns`,
`reminderQuietMinutes`, `digestItems`, `kinds` (e.g. add your own record kinds). Defaults: `lib/config.nx`.

## Tests
`npm install && npm test` — unit tests in `.nx` (tokenizer, IDF, scoring) + end-to-end through the real
MCP client (full lifecycle, purge phrase, broken files, hooks, path traversal, 400-record scale).

MIT.