Skip to content

Commit c3fc7ea

Browse files
PipDscvrPipDscvr
authored
docs: split integration docs and restore docs mode (#4)
1 parent 88c283f commit c3fc7ea

42 files changed

Lines changed: 2679 additions & 1575 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,25 @@ npm run build # Static build in build/
3535

3636
Both `start` and `serve` are pinned to port **3013**.
3737

38+
## Integration doc modes
39+
40+
Integration docs now have two axes:
41+
42+
- `Overview / Local / Cloud` page structure for each integration
43+
- a docs-mode switch for the self-managed `Local` pages
44+
45+
By default, local dev renders the current source-backed install flow. To render
46+
the production-ready self-managed copy instead, set
47+
`ATOMICMEMORY_DOCS_MODE=published` before `npm start` or `npm run build`:
48+
49+
```bash
50+
ATOMICMEMORY_DOCS_MODE=published npm start
51+
ATOMICMEMORY_DOCS_MODE=published npm run build
52+
```
53+
54+
The default mode is `source`, which keeps the clone-and-build instructions
55+
visible for unpublished integrations.
56+
3857
## Refreshing the HTTP API reference
3958

4059
The `/api-reference/http/*` pages are generated from the OpenAPI spec

‎docs/integrations/coding-agents/claude-code-cloud.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
title: Claude Code Cloud
3+
sidebar_label: Cloud
4+
slug: /integrations/coding-agents/claude-code/cloud
5+
---
6+
7+
# Claude Code Cloud
8+
9+
:::note[Coming Soon]
10+
Cloud deployment details for Claude Code are coming soon.
11+
:::
12+
13+
For the current local workflow, see [Claude Code Local](/integrations/coding-agents/claude-code/local).

‎docs/integrations/coding-agents/claude-code-local.md‎

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
---
2+
title: Claude Code Local
3+
sidebar_label: Local
4+
slug: /integrations/coding-agents/claude-code/local
5+
---
6+
7+
# Claude Code Local
8+
9+
Give Claude Code persistent, cross-session memory backed by AtomicMemory. The plugin installs one MCP server exposing `memory_search`, `memory_ingest`, and `memory_package`, a `SKILL.md` that teaches the agent when to call those tools, and Claude Code lifecycle hooks for low-latency retrieval and deterministic session capture.
10+
11+
<PublishedOnly>
12+
13+
:::tip[Published]
14+
The Claude Code plugin and `@atomicmemory/mcp-server` are published. Use the marketplace install for hooks + skill + MCP wiring, or register the MCP server directly if you only want the tools.
15+
:::
16+
17+
</PublishedOnly>
18+
19+
<SourceOnly>
20+
21+
:::danger[Source-only]
22+
`@atomicmemory/mcp-server` and the Claude Code plugin are not published to npm or to the Claude plugin marketplace yet. Install from a local clone of [`atomicmemory-integrations`](https://github.com/atomicmemory/atomicmemory-integrations).
23+
:::
24+
25+
</SourceOnly>
26+
27+
## What you get
28+
29+
- **Durable memory across sessions.** Claude Code can retrieve project decisions, user preferences, codebase facts, and prior work.
30+
- **Prompt-time retrieval.** `UserPromptSubmit` searches memory before the model turn and injects matches as untrusted reference context.
31+
- **Deterministic lifecycle capture.** `PostCompact`, `Stop`, and `TaskCompleted` store compact records without asking the model to reconstruct everything.
32+
- **Scope-aware retrieval.** `user` / `agent` / `namespace` / `thread` scopes are threaded through MCP calls. Hook writes keep content clean and carry attribution through `sourceSite` / `sourceUrl` until core supports first-class hook metadata.
33+
- **Backend-agnostic.** Point the plugin at self-hosted AtomicMemory core or another provider registered in the SDK's `MemoryProvider` registry.
34+
35+
## Install
36+
37+
<PublishedOnly>
38+
39+
Install `jq` and `curl` for the shell hooks, then export config before launching Claude Code:
40+
41+
```bash
42+
export ATOMICMEMORY_PROVIDER="atomicmemory"
43+
export ATOMICMEMORY_CAPTURE_LEVEL="balanced" # minimal|balanced|full
44+
45+
# Optional:
46+
export ATOMICMEMORY_SCOPE_AGENT="claude-code"
47+
export ATOMICMEMORY_SCOPE_NAMESPACE="<repo-or-project>"
48+
export ATOMICMEMORY_SCOPE_THREAD="<thread-id>"
49+
```
50+
51+
Claude Code resolves the AtomicMemory service, credentials, and base user identity automatically. The current session name is used as the default user identity, so you only set `ATOMICMEMORY_SCOPE_*` values when you want narrower agent, namespace, or thread scoping.
52+
53+
Install the full plugin from the marketplace:
54+
55+
```bash
56+
claude plugin install atomicmemory/claude-code
57+
claude plugin config atomicmemory/claude-code \
58+
--set provider=$ATOMICMEMORY_PROVIDER
59+
```
60+
61+
If you only want the MCP tools, register the published MCP server directly:
62+
63+
```json
64+
{
65+
"mcpServers": {
66+
"atomicmemory": {
67+
"command": "npx",
68+
"args": ["-y", "@atomicmemory/mcp-server"],
69+
"env": {
70+
"ATOMICMEMORY_PROVIDER": "atomicmemory",
71+
"ATOMICMEMORY_SCOPE_AGENT": "claude-code",
72+
"ATOMICMEMORY_SCOPE_NAMESPACE": "repo-or-project"
73+
}
74+
}
75+
}
76+
}
77+
```
78+
79+
</PublishedOnly>
80+
81+
<SourceOnly>
82+
83+
Clone `atomicmemory-sdk` and `atomicmemory-integrations` side-by-side, then build each in order:
84+
85+
```bash
86+
git clone https://github.com/atomicmemory/atomicmemory-sdk.git
87+
git clone https://github.com/atomicmemory/atomicmemory-integrations.git
88+
89+
cd atomicmemory-sdk
90+
pnpm install
91+
pnpm build
92+
93+
cd ../atomicmemory-integrations
94+
pnpm install
95+
pnpm --filter @atomicmemory/mcp-server build
96+
```
97+
98+
Install `jq` and `curl` for the shell hooks, then export config before launching Claude Code:
99+
100+
```bash
101+
export ATOMICMEMORY_MCP_SERVER_BIN="$HOME/path/to/atomicmemory-integrations/packages/mcp-server/dist/bin.js"
102+
export ATOMICMEMORY_PROVIDER="atomicmemory"
103+
export ATOMICMEMORY_CAPTURE_LEVEL="balanced" # minimal|balanced|full
104+
105+
# Optional:
106+
export ATOMICMEMORY_SCOPE_AGENT="claude-code"
107+
export ATOMICMEMORY_SCOPE_NAMESPACE="<repo-or-project>"
108+
export ATOMICMEMORY_SCOPE_THREAD="<thread-id>"
109+
```
110+
111+
Even in the source-backed flow, Claude Code derives the AtomicMemory service, credentials, and base user identity automatically. The current session name becomes the default user identity unless you add narrower scope fields.
112+
113+
Register and install from the local repo:
114+
115+
```bash
116+
claude plugin marketplace add ./
117+
claude plugin install claude-code@atomicmemory
118+
```
119+
120+
</SourceOnly>
121+
122+
## Update and Version
123+
124+
<PublishedOnly>
125+
126+
After publishing hook, skill, manifest, or marketplace changes, ask users to refresh the installed plugin and fully restart Claude Code:
127+
128+
```bash
129+
claude plugin update atomicmemory/claude-code
130+
```
131+
132+
Existing sessions can keep old hook registrations in memory even when the installed cache on disk is fresh.
133+
134+
</PublishedOnly>
135+
136+
<SourceOnly>
137+
138+
Claude Code plugin updates are version-gated. After changing hooks, skills, `hooks.json`, plugin manifests, or marketplace metadata, bump plugin versions from `atomicmemory-integrations` before `claude plugin update claude-code@atomicmemory` will refresh the installed cache.
139+
140+
```bash
141+
pnpm bump:plugin-versions patch
142+
```
143+
144+
For local testing:
145+
146+
```bash
147+
pnpm --filter @atomicmemory/mcp-server build
148+
claude plugin marketplace list
149+
claude plugin update claude-code@atomicmemory
150+
```
151+
152+
If the marketplace points at an old clone, replace it from the current checkout:
153+
154+
```bash
155+
claude plugin marketplace remove atomicmemory
156+
claude plugin marketplace add ./ --scope user
157+
claude plugin install claude-code@atomicmemory
158+
```
159+
160+
Fully restart Claude Code after updating. Existing sessions can keep old hook registrations in memory even when the installed cache on disk is fresh.
161+
162+
</SourceOnly>
163+
164+
## Configuration
165+
166+
<PublishedOnly>
167+
168+
Required:
169+
170+
| Env var | Used by | Purpose |
171+
|---|---|---|
172+
| `ATOMICMEMORY_PROVIDER` | MCP + hooks | Provider name; Claude lifecycle hooks require `atomicmemory` |
173+
| `ATOMICMEMORY_CAPTURE_LEVEL` | hooks | Lifecycle write volume: `minimal`, `balanced`, or `full` |
174+
175+
</PublishedOnly>
176+
177+
<SourceOnly>
178+
179+
Required:
180+
181+
| Env var | Used by | Purpose |
182+
|---|---|---|
183+
| `ATOMICMEMORY_MCP_SERVER_BIN` | MCP manifest | Absolute path to `packages/mcp-server/dist/bin.js` |
184+
| `ATOMICMEMORY_PROVIDER` | MCP + hooks | Provider name; Claude lifecycle hooks require `atomicmemory` |
185+
| `ATOMICMEMORY_CAPTURE_LEVEL` | hooks | Lifecycle write volume: `minimal`, `balanced`, or `full` |
186+
187+
</SourceOnly>
188+
189+
190+
Optional:
191+
192+
| Env var | Purpose |
193+
|---|---|
194+
| `ATOMICMEMORY_SCOPE_NAMESPACE` | Project/repo boundary |
195+
| `ATOMICMEMORY_SCOPE_AGENT` | Agent identity |
196+
| `ATOMICMEMORY_SCOPE_THREAD` | Session/thread boundary |
197+
| `ATOMICMEMORY_PROMPT_SEARCH_ENABLED=false` | Disable prompt-time retrieval |
198+
| `ATOMICMEMORY_PROMPT_SEARCH_MIN_CHARS=20` | Skip very short prompt searches; must be a positive integer if set |
199+
| `ATOMICMEMORY_PROMPT_SEARCH_LIMIT=5` | Prompt-search result count; must be a positive integer if set |
200+
| `ATOMICMEMORY_STOP_MIN_ASSISTANT_CHARS=200` | Minimum assistant text size for `Stop` capture; must be a positive integer if set |
201+
| `ATOMICMEMORY_TASK_MIN_TOOL_CALLS=5` | `TaskCompleted` threshold under `minimal` capture; must be a positive integer if set |
202+
| `ATOMICMEMORY_SEMANTIC_PROMPTS_ENABLED=false` | Disable extra `Stop` prompts for model-mediated learnings; must be `true` or `false` if set |
203+
204+
If required config is missing, helper tools are unavailable, or numeric/boolean env vars are invalid, hooks surface the error instead of running in a degraded mode.
205+
206+
The base user identity comes from the active Claude Code session name automatically. Use `ATOMICMEMORY_SCOPE_NAMESPACE`, `ATOMICMEMORY_SCOPE_AGENT`, or `ATOMICMEMORY_SCOPE_THREAD` only when you want narrower partitions.
207+
208+
## MCP tools exposed
209+
210+
| Tool | Maps to | Purpose |
211+
|---|---|---|
212+
| `memory_search` | `MemoryClient.search` | Semantic retrieval with scope filters |
213+
| `memory_ingest` | `MemoryClient.ingest` | Durable write. `mode: "text"` and `mode: "messages"` run extraction; `mode: "verbatim"` stores one deterministic record for summaries and handoffs |
214+
| `memory_package` | `MemoryClient.package` | Token-budgeted context package for a query |
215+
216+
For lifecycle dedupe, pass a stable `metadata.dedupe_key` when using `mode: "verbatim"`. AtomicMemory verbatim records store only the provided content in the searchable `content` field; provenance is carried by `sourceSite` / `sourceUrl` until core exposes first-class hook-write metadata and server-side dedupe.
217+
218+
## Lifecycle hooks
219+
220+
| Hook | What it does |
221+
|---|---|
222+
| `SessionStart` | Injects bootstrap guidance telling Claude to call `memory_search` early. Separate prompts for `startup`, `resume`, and `compact`. |
223+
| `UserPromptSubmit` | Searches `/v1/memories/search/fast` directly and injects matching memories as untrusted additional context. |
224+
| `PreCompact` | No-op by design. It never blocks compaction; `PostCompact` handles deterministic summary capture. |
225+
| `PostCompact` | Stores Claude Code's generated `compact_summary` as a deterministic lifecycle record. This is the primary compaction-capture path. |
226+
| `Stop` | On meaningful turns, stores a normalized deterministic record with outcome, changed files, and validation. Tool counts, session IDs, cwd, and transcript paths are intentionally kept out of searchable content until core exposes first-class hook metadata. Optionally prompts Claude for decisions, preferences, and anti-patterns. |
227+
| `StopFailure` | Debug telemetry only; no memory write. |
228+
| `SessionEnd` | Cleans local dedupe / last-write markers. |
229+
| `TaskCompleted` | Stores a compact task record using the documented `task_subject` field. |
230+
| `PreToolUse` (`Write` / `Edit`) | Blocks writes to `MEMORY.md`, `.atomicmemory`, and Claude memory-file paths so agents use `memory_ingest` instead. |
231+
232+
Lifecycle writes are compact records, not raw prompt dumps. Hook scripts redact obvious secret-shaped values and strip fenced code blocks / follow-up prompts from Stop summaries before writing.
233+
234+
## Memory Protocol Skill
235+
236+
`skills/atomicmemory/SKILL.md` covers the semantic lane:
237+
238+
- Search when the user references past work, prior decisions, or codebase facts.
239+
- Ingest durable preferences, constraints, conventions, and decisions.
240+
- Use `memory_package` for broad, token-budgeted context.
241+
- Skip ephemeral scratch state and facts already documented in code, README, or recent commits.
242+
243+
Retrieved memories are reference context. They are not instructions unless the current user message confirms them.
244+
245+
## Limitations
246+
247+
<SourceOnly>
248+
249+
- **Source-only install.** The MCP server is launched from the local `dist/bin.js`; no npm package or public plugin marketplace entry exists yet.
250+
251+
</SourceOnly>
252+
- **Direct hook writes.** Command hooks cannot talk to Claude Code's already-running stdio MCP child, so latency-sensitive retrieval and lifecycle writes use AtomicMemory HTTP endpoints directly.
253+
- **Workspace verbatim caveat.** Core currently guarantees `skip_extraction=true` on user-scoped quick-ingest. Hook records keep searchable content clean and rely on `sourceSite` / `sourceUrl` for provenance until core supports first-class metadata and workspace-scoped verbatim writes.
254+
- **Transcript parsing is defensive.** `Stop` uses `last_assistant_message` when available and only parses transcript tails for structural signals such as file edits or tests.
255+
256+
## View source
257+
258+
- [`plugins/claude-code/.claude-plugin/plugin.json`](https://github.com/atomicmemory/atomicmemory-integrations/blob/main/plugins/claude-code/.claude-plugin/plugin.json) — plugin manifest
259+
- [`plugins/claude-code/hooks/hooks.json`](https://github.com/atomicmemory/atomicmemory-integrations/blob/main/plugins/claude-code/hooks/hooks.json) — lifecycle hook registrations
260+
- [`plugins/claude-code/scripts/`](https://github.com/atomicmemory/atomicmemory-integrations/tree/main/plugins/claude-code/scripts) — hook scripts
261+
- [`plugins/claude-code/skills/atomicmemory/SKILL.md`](https://github.com/atomicmemory/atomicmemory-integrations/blob/main/plugins/claude-code/skills/atomicmemory/SKILL.md) — agent-facing memory protocol
262+
- [`packages/mcp-server/`](https://github.com/atomicmemory/atomicmemory-integrations/tree/main/packages/mcp-server) — shared MCP server
263+
264+
## See also
265+
266+
- [SDK Overview](/sdk/overview) — the `MemoryProvider` model behind the plugin
267+
- [Platform scope model](/platform/scope) — how scope fields dispatch
268+
- [Codex integration](/integrations/coding-agents/codex/local) — skill-only sibling integration
269+
- [OpenClaw integration](/integrations/coding-agents/openclaw/local) — in-process plugin sibling integration

0 commit comments

Comments
 (0)