memory

Personal MCP memory server. Multi-user, file-backed, cross-platform.

Each user gets an isolated namespace. Memories persist across sessions within the namespace.

Usage

Lifecycle

xmszm-memory has three separate steps. Do not confuse MCP connection with automatic memory loading.

1. Configure MCP
   -> The client can see xmszm-memory tools.

2. First-use initialization
   -> initialize(namespace, profile?) creates boot/personality memories.
   -> boot_instructions(namespace, target?) generates the client rule to install into AGENTS.md, CLAUDE.md, .cursorrules, or global instructions.

3. Normal conversations
   -> The installed client rule makes each new session call initialize(...) and read(..., "system://boot") before answering.
   -> During conversation, the model uses search/read/list to recall memory and create/update/delete to maintain durable memory.

Important: MCP servers cannot force clients to call tools at session start. Automatic memory loading only works after the returned boot_instructions rule is installed in the client or project instructions.

Requirements

Node.js >= 18 (if installed via npm)
No installation needed if using npx

stdio mode (for MCP clients)

npx -y @xmszm/memory

SSE mode (HTTP server, background service)

npx -y @xmszm/memory sse
npx -y @xmszm/memory sse 3000

Hermes Configuration

{
  "mcpServers": {
    "xmszm-memory": {
      "command": "npx",
      "args": ["-y", "@xmszm/memory"]
    }
  }
}

Claude Code Configuration

User-scope example:

claude mcp add -s user xmszm-memory -- npx -y @xmszm/memory

JSON example:

{
  "mcpServers": {
    "xmszm-memory": {
      "command": "npx",
      "args": ["-y", "@xmszm/memory"]
    }
  }
}

Cursor / Windsurf / Any MCP Client

Most MCP-compatible clients accept the same format:

{
  "mcpServers": {
    "xmszm-memory": {
      "command": "npx",
      "args": ["-y", "@xmszm/memory"]
    }
  }
}

Memory Model

Memories are URI-only records. There is no key field and no key-based API.

interface Memory {
  uri: string;
  content: string;
  disclosure: string;
  priority: 0 | 1 | 2; // default 2
  tags: string[];      // default []
  source: string;      // default "assistant_inferred"
  createdAt: string;
  updatedAt: string;
  deletedAt?: string;  // set by delete()
}

Deleted memories are soft-deleted with deletedAt and are excluded from read, search, and list by default.

Tools

Tool	Description
`initialize(namespace, profile?)`	Idempotently create v2.1 boot/personality memories. `profile` defaults to `assistant`; accepted values are `assistant` and `blank`. Active existing memories are skipped, never overwritten.
`boot_instructions(namespace, target?)`	Generate copy-paste startup instructions for a client/global/project rule so future sessions call `initialize` and `read(system://boot)` before answering. Targets: `generic`, `project`, `claude-code`, `codex`, `cursor`, `windsurf`.
`create(namespace, uri, content, disclosure, priority?, tags?, source?)`	Create a new memory. Refuses overwrite if `uri` already exists; use `update` to modify.
`update(namespace, uri, fields)`	Update an existing active memory by exact URI without changing `createdAt`. `fields` can include `content`, `disclosure`, `priority`, `tags`, or `source`.
`read(namespace, uri)`	Read one active memory by exact URI. Special reads: `system://boot` and `system://diagnostic/identity`.
`search(namespace, query)`	Main entry when URI is unknown. Searches `uri`, `content`, `disclosure`, `tags`, and `source`.
`list(namespace, prefix?)`	Browse active memories, optionally filtered by URI prefix.
`delete(namespace, uri)`	Soft-delete one active memory by exact URI by setting `deletedAt`.
`list_namespaces()`	List all namespaces only; it does not return memories.

First-use Initialization

After MCP is configured, ask the client once to initialize the namespace and generate its startup rule.

Recommended first prompt:

Use xmszm-memory. Call initialize("admin", "assistant"), then read("admin", "system://boot"), then call boot_instructions("admin", "<target>") and install the returned rule into this client's global or project instructions.

Use target claude-code, codex, cursor, windsurf, project, or generic.

Boot Flow

At the start of a new session, clients should initialize the namespace once if it may be empty, then read the boot context before answering:

initialize(namespace, "assistant")  # or initialize(namespace, "blank")
read(namespace, "system://boot")

initialize is safe to call repeatedly. It reports created and skipped_active_existing URIs and never overwrites an active memory.

Profiles:

Profile	Behavior
`assistant`	Creates default identity, verification, no-fake-execution, conflict-resolution, user-relationship, boundary, reality, and coding-workflow memories.
`blank`	Creates only minimal structural placeholders such as `identity://default/self` and boundaries; it does not assume user-specific preferences.

Special reads:

URI	Behavior
`system://boot`	Returns active `identity://default/*` memories plus all active `priority=0` memories, de-duplicated by URI and sorted by URI. Includes a short routing guide.
`system://diagnostic/identity`	Reports whether core identity URIs are present, missing, active count, priority-0 count, and warnings for missing boundaries, verification, or no-fake-execution memories.

Recommended memory flow:

Configure MCP once -> client can see xmszm-memory tools
First use once -> initialize(namespace, profile?) -> read(namespace, "system://boot") -> boot_instructions(namespace, target?) -> install returned rule
Every new session -> installed rule triggers initialize(namespace, profile?) -> read(namespace, "system://boot")
Unknown URI -> search(namespace, query) -> read/update/delete(namespace, exactUri)
Browse URI prefix -> list(namespace, prefix)
Create new memory -> create(namespace, uri, ...)
Modify existing memory -> update(namespace, uri, fields)

Examples:

initialize("admin")
initialize("admin", "blank")
read("admin", "system://boot")
read("admin", "system://diagnostic/identity")
boot_instructions("admin", "generic")
boot_instructions("admin", "codex")

To make memory load automatically, run boot_instructions(namespace, target?) once and copy the returned rule into the client global instructions or project rule file. Without that client-side rule, the MCP server is available but the model may not call it until asked.

Data

Stored in ~/.xmszm-memory/ as one JSON file per namespace.

# View all your memories
cat ~/.xmszm-memory/admin.json

License

MIT

Built from the design philosophy of Nocturne Memory by NeuronActivation.

xmszm-memory