# Install the Meaning Model

This guide installs the Meaning Model MCP server and connects it to an AI
assistant. It is written so that an agent such as Claude Code or Codex can
follow it step by step. A person can follow it too.

If you are an agent: tell the user what you are about to install and change
before you do it. Ask before editing any configuration file, and never remove
other servers from it. If a step fails, stop and report the error instead of
working around it.

## What gets installed

- The npm package `@emergent-wisdom/meaning-model-mcp`: an MCP server that runs
  locally over stdio. It includes the bundled browser viewer.
- Its native engine: a prebuilt executable downloaded from the project's
  official GitHub release and checked against its SHA-256 digest.
- A private SQLite database file that keeps models, stories and memory across
  sessions.

Running it needs no account, API key or online service.

## 1. Check the requirements

- Node.js 22.18 or newer. Run `node --version`. If Node.js is missing or older,
  ask the user to install the current LTS release from https://nodejs.org and
  stop here.
- A prebuilt engine exists for macOS 14 or newer (Apple Silicon or Intel),
  Linux x64 with glibc 2.35 or newer, and Windows x64. On other platforms, use
  the source build in step 3.

## 2. Choose the folders

Use these defaults unless the user wants other locations:

- Installation folder: `~/meaning-model`
- Data folder: `~/meaning-model/data`

Keep the data folder outside `node_modules`. Create both folders:

```sh
mkdir -p ~/meaning-model/data
```

On Windows (PowerShell): `mkdir $HOME\meaning-model\data`

## 3. Install the package and its engine

```sh
cd ~/meaning-model
npm install @emergent-wisdom/meaning-model-mcp
npx meaning-model-mcp --install-engine
```

If no prebuilt engine exists for the platform, build it from the included
source instead. This needs Cargo, a C compiler and native build tools:

```sh
npx meaning-model-mcp --build-engine
```

Then work out three absolute paths, replacing `~` with the user's real home
folder:

- LAUNCHER: `~/meaning-model/node_modules/@emergent-wisdom/meaning-model-mcp/mcp-server/bin/meaning-model-mcp.mjs`
- STATE_FILE: `~/meaning-model/data/meaning-model.sqlite`. The engine creates
  this file on its first write.
- NODE: the output of `command -v node` (Windows: `where node`). Desktop apps
  often cannot find `node` on their own, so use this full path as the command.

Check that LAUNCHER exists before continuing.

## 4. Connect the assistant

Ask the user which assistant to connect. Add the server and keep every entry
that is already there.

### Claude Code

```sh
claude mcp add meaning-model -s user -e LIFE_SIM_STATE_FILE=STATE_FILE -- NODE LAUNCHER
```

`-s user` makes the server available in every project. Start a new Claude Code
session to load it.

### Claude Desktop

Open the configuration from Settings → Developer → Edit Config, or edit the
file directly:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Add this entry under `mcpServers`, with the real paths:

```json
{
  "mcpServers": {
    "meaning-model": {
      "command": "NODE",
      "args": ["LAUNCHER"],
      "env": { "LIFE_SIM_STATE_FILE": "STATE_FILE" }
    }
  }
}
```

Then quit and reopen Claude Desktop.

### Codex

Add this to `~/.codex/config.toml`:

```toml
[mcp_servers.meaning-model]
command = "NODE"
args = ["LAUNCHER"]

[mcp_servers.meaning-model.env]
LIFE_SIM_STATE_FILE = "STATE_FILE"
```

Start a new Codex session to load it.

### Other MCP clients

Configure a stdio server with the command `NODE`, the single argument
`LAUNCHER`, and the environment variable `LIFE_SIM_STATE_FILE` set to
`STATE_FILE`.

### Optional add-ons

The storytelling add-on writes fiction from a model and gives feedback on a
person's own writing. The alien add-on searches for solution ideas through
invented worlds. To enable them, add the environment variable
`MEANING_MODEL_ADDONS` with the value `storytelling`, `alien` or
`storytelling,alien`, in the same place as `LIFE_SIM_STATE_FILE`. Modeling and
memory are always on.

### One database per running server

Each assistant session starts its own server process. Use one session at a
time with a given database file. If the user works with several assistants at
once, give each its own STATE_FILE.

## 5. Check that it works

In a new session of the connected assistant, call the tool `life_engine_status`.
Look at `persistence.rustAuthority`. If it says `process-memory`, the state file
was not picked up, and work would be lost when the session ends. In that case,
check the `LIFE_SIM_STATE_FILE` setting and that the data folder exists.

## 6. Start using it

Tell the user it is ready, and suggest a first request, for example:

- "Build a model of my project, with its main processes, and open it in the viewer."
- "Model the coffee market over the last ten years and explain what drove the price."
- "Remember what we decided today and why. Pick it up again next time."
- "Find my saved work and continue it."
- With the storytelling add-on: "Give me feedback on this chapter," or "Write a short story from a world you model first."

The viewer opens as a local link in the browser. It works only on the same
computer as the server.

## Upgrade

```sh
cd ~/meaning-model
npm install @emergent-wisdom/meaning-model-mcp@latest
npx meaning-model-mcp --install-engine
```

Keep the same STATE_FILE so that saved work carries over. Run the engine step
again after every package upgrade.

## Uninstall

Remove the `meaning-model` entry from the assistant's configuration, then
delete the installation folder. The database file holds the user's models,
stories and memory: ask the user before deleting it.

## More

- Source code, papers and the full guides: https://github.com/emergent-wisdom/meaning-model
- npm package: https://www.npmjs.com/package/@emergent-wisdom/meaning-model-mcp