@soulid/adapter-claude-code

SOUL ID runtime adapter for Claude Code — reads a Claude Code project and produces a portable Soul Document.

Install

npm install @soulid/adapter-claude-code

File mapping (SOUL ID v0.3 spec)

| Claude Code file | → Soul Document field | |---|---| | CLAUDE.md (H1 or "You are X") | name | | CLAUDE.md (first sentence) | purpose | | CLAUDE.md ## Values / Principles | values | | CLAUDE.md keywords | capabilities (inferred) | | .memory/*.md | memory.topics (pointer-index) | | (always) | runtime_hints (claude-code preset) |

Architecture based on RFC-SOULID-0003 and the Claude Code memory architecture (2026-03-31).

Usage

import { fromWorkspace, toWorkspace, initMemoryDir } from '@soulid/adapter-claude-code'

// Parse CLAUDE.md + .memory/ → Soul Document
const doc = fromWorkspace({
  projectPath: '/path/to/project',
  namespace: 'soulid',
  overrides: {
    soul_id: 'soulid:pedro-sre:v1:001',
  }
})

console.log(doc.soul_id)      // soulid:pedro-sre:v1:001
console.log(doc.name)         // from CLAUDE.md H1
console.log(doc.values)       // from ## Values section
console.log(doc.capabilities) // inferred from keywords
console.log(doc.memory.topics)// .memory/*.md filenames

// Inject soul identity block into CLAUDE.md
toWorkspace(doc, { projectPath: '/path/to/project' })

// Scaffold .memory/ topic files (idempotent)
initMemoryDir({
  projectPath: '/path/to/project',
  topics: ['identity', 'decisions', 'context', 'todos']
})

API

fromWorkspace(opts?)

Parses a Claude Code project into a partial SoulDocument.

fromWorkspace({
  projectPath?: string,             // defaults to process.cwd()
  namespace?: string,               // soul_id namespace, default 'soulid'
  overrides?: Partial<SoulDocument>
}): Partial<SoulDocument>

toWorkspace(doc, opts?)

Prepends a <!-- soul:start/end --> identity block to CLAUDE.md. Safe — never overwrites content below the block.

initMemoryDir(opts?)

Scaffolds .memory/ topic files and adds CLAUDE.local.md to .gitignore.

initMemoryDir({
  projectPath?: string,
  topics?: string[]   // default: ['identity', 'decisions', 'context', 'todos']
}): void

readWorkspace(opts?)

Returns raw file contents.

readWorkspace({ projectPath?: string }): {
  claudeMd?: string
  topicFiles: Record<string, string>  // filename → content
  claudeLocalMd?: string
}

Memory architecture

This adapter implements Claude Code's pointer-index memory strategy:

• CLAUDE.md — lightweight index (~150 chars/line pointers)
• .memory/<topic>.md — loaded on demand, never all at once
• CLAUDE.local.md — machine-local context, gitignored
• Transcripts are grep'd for identifiers, never fully reloaded

Spec

Implements RFC-SOULID-0003 Runtime Adapter interface:

runtime:              "claude-code"
soul_file:            "CLAUDE.md"
memory_strategy:      "pointer-index"
strict_write_discipline: true
grep_over_reload:     true

License

MIT — soulid.io