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:

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

Generate a token scoped to the soul:

./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:

{
  "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_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, to avoid clobbering concurrent edits

Content Structure

/index.md          — Hub page linking to all sections
/architecture.md   — System design, module boundaries, key decisions
/patterns.md       — Code patterns, conventions, idioms
/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
/guide.md          — This document

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