npm package: @soulid/adapter-claude-code
Description: SOUL ID runtime adapter for Claude Code — read/write Soul Documents from CLAUDE.md and .memory/ topic files
Author: soulid.io
Latest version: 0.1.0

# @soulid/adapter-claude-code

[SOUL ID](https://soulid.io) runtime adapter for [Claude Code](https://claude.ai/code) — reads a Claude Code project and produces a portable Soul Document.

[![npm](https://img.shields.io/npm/v/@soulid/adapter-claude-code)](https://www.npmjs.com/package/@soulid/adapter-claude-code)
[![spec](https://img.shields.io/badge/spec-v0.3-purple)](https://soulid.io/docs)

## Install

```bash
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](https://soulid.io/docs) and the Claude Code memory architecture (2026-03-31).

## Usage

```typescript
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`.

```typescript
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`.

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

### `readWorkspace(opts?)`

Returns raw file contents.

```typescript
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](https://soulid.io/docs) 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](https://soulid.io)