# Guide: Setting Up demarkus-soul

How to connect a Claude Code agent to demarkus-soul so it can read and write its own knowledge base.

## Prerequisites

- A running demarkus server with a content root for the soul
- The `demarkus-mcp` binary built from the client module
- An auth token with publish access to the soul's paths

## Server Setup

Run a dedicated demarkus server instance for the soul. Use a separate port to keep it isolated from other content:

```bash
./server/bin/demarkus-server -root /path/to/soul-content -port 6310
```

Generate a token scoped to the soul:
```bash
./tools/bin/demarkus-token generate -paths "/*" -ops publish,archive -tokens /path/to/soul-content/tokens.toml
```

Save the raw token — it's shown once and never stored in plaintext on the server.

## Claude Code MCP Configuration

Create `.mcp.json` in the project root:

```json
{
  "mcpServers": {
    "demarkus-soul": {
      "command": "/path/to/client/bin/demarkus-mcp",
      "args": [
        "-host", "mark://localhost:6310",
        "-token", "<raw-token>",
        "-insecure"
      ]
    }
  }
}
```

The `-insecure` flag skips TLS verification for localhost development. For remote servers, use proper TLS certificates — you can provide your own via the install script's `--tls-cert` and `--tls-key` flags, or use Let's Encrypt with `--domain`.

## Available MCP Tools

Once connected, the agent has these tools:

- **mark_fetch** — Read a document
- **mark_publish** — Create or update a document (with optimistic concurrency)
- **mark_append** — Append content to an existing document (journals, notes)
- **mark_list** — List documents in a directory
- **mark_archive** — Archive a document
- **mark_versions** — View version history
- **mark_graph** — Crawl link graph from a document

## How the Agent Should Use It

1. **Start of session**: Fetch `/index.md` and key pages to load context
2. **During work**: Update pages when learning something new (architecture insights, bug patterns, etc.)
3. **End of session**: Add a journal entry at `/journal.md` if something significant happened
4. **Always**: Use `expected_version` from a prior fetch when publishing or appending
5. **Appending**: Use `mark_append` for adding content to existing pages (journal entries, thoughts). It sends only the new content — no need to fetch-concat-republish. `expected_version` is mandatory.

## Content Structure

```
/index.md          — Hub page linking to all sections
/architecture.md   — System design, module boundaries, key decisions
/patterns.md       — Code patterns, conventions, build commands, workflow
/debugging.md      — Lessons from bugs and investigations
/roadmap.md        — What's next, what's in flight, what's done
/journal.md        — Session notes and evolution log
/thoughts.md       — Agent reflections, ideas, open questions
/guide.md          — This document
```

Each page is versioned. Every publish creates a new immutable version. The agent's knowledge accumulates over time, never lost.