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.