### Run the app - install and start

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/packages/create-app/README.md

After scaffolding, change into the app directory, install dependencies, and start the app. The query() method returns recent chronicles by default; pass semantic: true for relevance ranking.

```bash
cd my-awesome-app
npm install
npm start
```

--------------------------------

### Setup: Clone, install, and build the CLI

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/CONTRIBUTING.md

Clones the repository, installs dependencies, and builds the CLI. Requires Node.js >= 18 and npm or pnpm.

```bash
git clone https://github.com/Mnemosyne-OS/Mnemosyne-Neural-OS.git
cd Mnemosyne-Neural-OS/cli
npm install
npm run build
```

--------------------------------

### Install and launch MnemoForge CLI

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/README.md

Install the MnemoForge CLI globally via npm and start the interactive dashboard. Requires Node.js and npm.

```bash
npm install -g @mnemosyne_os/forge
mnemoforge
```

--------------------------------

### Install @mnemosyne_os/sdk

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/packages/sdk/README.md

Install the SDK package from npm.

```bash
npm install @mnemosyne_os/sdk
```

--------------------------------

### Run the cartridge with pnpm scripts (dev, test, typecheck)

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/examples/cartridge-boilerplate/README.md

Commands to install dependencies and start the development server on 127.0.0.1:5185 with strict port, run the included vitest test, and typecheck tests (which the build deliberately leaves out).

```bash
pnpm install
pnpm dev          # vite on 127.0.0.1:5185 (strictPort)
pnpm test         # vitest, jsdom — one example test ships with the template
pnpm typecheck    # types the tests too, which the build deliberately does not
```

--------------------------------

### Install @mnemosyne_os/affine-reader

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/packages/affine-reader/README.md

Install the package. Runtime dependency is yjs.

```bash
npm install @mnemosyne_os/affine-reader
```

--------------------------------

### Install @mnemosyne_os/design-sdk (npm)

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/packages/design-sdk/README.md

Use this command to install the design-sdk package. Requires Node.js and npm.

```bash
npm install @mnemosyne_os/design-sdk
```

--------------------------------

### Quick Start: Configure and use Mnemosyne Forge

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/cli/README.md

Five-step quick start: initialize chronicle, configure Ollama, open REPL, write a chronicle, and browse the vault.

```bash
# 1. Configure your vault + Resonance profile
mnemoforge chronicle init

# 2. Configure Local AI (Ollama)
mnemoforge config ollama
# → Detects Ollama, lists models, saves your choice

# 3. Open interactive REPL
mnemoforge forge

# 4. Write a chronicle (interactive)
mnemoforge chronicle commit

# 5. Browse your vault
mnemoforge chronicle open
```

--------------------------------

### MnemoVault Path Example

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/standards/ai-soul-passport/README.md

Example path for a specific passport file.

```text
~/Documents/MnemoVault/.soul-passport/ASTRA-65268BB4.passport.json
```

--------------------------------

### Run MCP server preview (mnemoforge serve)

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/cli/docs/07-mcp-server.md

Commands to run the MCP server preview (v1.3.8). The first starts the server with default settings; the second starts it on port 4000.

```bash
mnemoforge serve
mnemoforge serve --port 4000
```

--------------------------------

### Scaffold a new app with create-app

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/packages/README.md

Scaffolds a new Mnemosyne OS project with the create-app package, then starts the development server. Use this when starting from scratch rather than wiring packages by hand.

```bash
npm create @mnemosyne_os/app my-app
cd my-app
npm run dev
```

--------------------------------

### Install @mnemosyne_os/public-contracts with npm

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/packages/public-contracts/README.md

Install the package with npm. zod is the only runtime dependency.

```bash
npm i @mnemosyne_os/public-contracts
```

--------------------------------

### Full app.manifest.json example

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/packages/sdk/docs/MANIFEST.md

Complete example of an app.manifest.json with all optional fields. The OS validates this at register() and enforces declared scopes/intents on every RPC; anything not declared is rejected. Unknown fields are allowed because the schema is not strict.

```json
{
  "id":            "my-app",
  "name":          "My App",
  "version":       "1.0.0",
  "author":        "Your Name",
  "mnemosyne_sdk": "^1.2.0",
  "description":   "Short description of what your app does.",
  "scopes":        ["vault:read:DEV", "bridge:read"],
  "vaults":        ["DEV"],
  "intents":       ["QUERY", "BRIDGE_READ"],
  "max_chronicle_size_kb": 64,
  "requires_consent": false
}
```

--------------------------------

### Start Mnemosyne MCP with npx

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/packages/mcp/README.md

Run this command to start the Mnemosyne MCP server for any other MCP client. The server speaks standard JSON-RPC over stdio.

```bash
npx -y @mnemosyne_os/mcp
```

--------------------------------

### Verify installer attestation with gh attestation verify

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/README.md

Verifies that a downloaded Mnemosyne OS installer matches the build produced by the project's CI, using GitHub's Sigstore-backed attestation system. Run this command from the directory containing the installer file. A successful verification confirms the file's provenance; a failure indicates the file does not match the attested build.

```bash
gh attestation verify Mnemosyne-OS-Infinity-Setup-x64.exe -R Mnemosyne-OS/Mnemosyne-Neural-OS
```

--------------------------------

### mnemoforge workspace add-rule example

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/cli/docs/05-command-reference.md

Example of adding a rule to the `npm` section of the workspace.

```bash
mnemoforge workspace add-rule "Never publish outside @mnemosyne_os scope" --section npm
```

--------------------------------

### Resume a project with mnemosyne_get_position and mnemosyne_update_position

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/packages/mcp/RECIPES.md

Use at session start to get the position for a resonance, and at session end to update it. This pair keeps track of the project state.

```text
At session start:  use mnemosyne_get_position for the resonance "auth-migration".
At session end:    use mnemosyne_update_position for "auth-migration" with what
                   was done and what comes next.
```

--------------------------------

### Verify Forge CLI installation

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/cli/docs/01-getting-started.md

Checks the installed version of the Forge CLI.

```bash
mnemoforge --version
```

--------------------------------

### mnemoforge chronicle archive example

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/cli/docs/05-command-reference.md

Example of archiving a specific chronicle file.

```bash
mnemoforge chronicle archive --file "handbook/chronicles/CHRONICLE-2026-04-05-my-decision.md"
```

--------------------------------

### Boot sequence with MnemoCartridgeSDK

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/packages/cartridge-sdk/README.md

Initializes the SDK with a plugin identifier, then performs the recommended boot sequence: ensure a sandbox vault, declare a vault tile with metrics, and ingest social data. The host computes vault numbers even when the app is closed, and writes are deduplicated via SHA-256.

```ts
import { MnemoCartridgeSDK } from '@mnemosyne_os/cartridge-sdk';

const sdk = new MnemoCartridgeSDK('@mnemosyne-plugins/my-app');

// 1. Own sandbox vault — isolated until the HUMAN unlocks permanence.
const sb = await sdk.ensureSandbox();          // → { vault: 'APP-…', unlocked }

// 2. Declare your vault tile — the host computes the numbers, even app-closed.
await sdk.describeVaultTile({
  icon: '🏝️',
  metrics: [{ label: 'Contacts', spine: 'SOCIAL_CONTACT' }],
});

// 3. Write into YOUR vault (SHA-256 dedup host-side).
await sdk.socialIngest(sb.vault, 'Contact: Léa. …', 'SOCIAL_CONTACT');
```

--------------------------------

### Install Forge CLI globally

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/cli/docs/01-getting-started.md

Installs the @mnemosyne_os/forge package globally using npm.

```bash
npm install -g @mnemosyne_os/forge
```

--------------------------------

### Create WORKSPACE.json

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/cli/docs/01-getting-started.md

Instructions to create the WORKSPACE.json file manually or copy the template.

```bash
# Create manually or copy the template
# .cli_resonance/WORKSPACE.json
```

--------------------------------

### SOUL_ID Format Example

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/standards/ai-soul-passport/README.md

Shows the SOUL_ID format as ASTRA-[8 chars hex] with an example ASTRA-65268BB4.

```text
ASTRA-[8 chars hex]      e.g. ASTRA-65268BB4
```

--------------------------------

### Verify workspace loads

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/cli/docs/01-getting-started.md

Runs the workspace show command to verify the WORKSPACE.json loads correctly.

```bash
mnemoforge workspace show
```

--------------------------------

### MCP Server commands

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/cli/README.md

Starts the MCP server on default or custom port.

```bash
mnemoforge serve                # start MCP server on port 3141
mnemoforge serve --port 4000    # custom port
```

--------------------------------

### Vitest Example Test File

Source: https://github.com/mnemosyne-os/mnemosyne-neural-os/blob/main/CONTRIBUTING_AI.md

Example test file for handlers using Vitest. Shows a happy path test and a placeholder for a failure path test.

```typescript
// electron/handlers/__tests__/example.handlers.test.ts
import { describe, it, expect, vi } from 'vitest'

describe('example handlers', () => {
  it('returns ok:true on valid input', async () => {
    const result = await processExample('valid-id', 'valid-payload')
    expect(result).toBe('processed:valid-id')
  })

  it('handles empty payload gracefully', async () => {
    // test failure path
  })
})
```