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_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.