docs(claude-code): rewrite in mem0 integration-doc shape#11
Closed
docs(claude-code): rewrite in mem0 integration-doc shape#11
Conversation
Generated with create-docusaurus@3.10.0 (classic preset, TypeScript). Structure: - docs/introduction.md (slug: /, landing page, placeholder) - docs/quickstart.md (placeholder) - docs/platform/ (6 placeholder pages: architecture, composition, stores, providers, scope, observability — the differentiator narrative, to be authored in Phase 3) - docs/api-reference/http/ (7 placeholder pages: ingest, search, list-get-delete, consolidate-decay-cap, lessons, audit, config — to be ported from atomicmemory-core/docs/api-reference.md in Phase 3) - docs/api-reference/sdk/coming-soon.md (SDK reference deferred until SDK ships public) Config: - docusaurus.config.ts — AtomicMemory branding, navbar (Platform + API Reference), footer links, GitHub link, dark/light theme auto - sidebars.ts — explicit sidebar definitions for platformSidebar + apiReferenceSidebar (not auto-generated) - static/CNAME — docs.atomicmemory.ai - .github/workflows/deploy.yml — GitHub Pages via actions/deploy-pages@v4 Build verified: npm run build succeeds (static files in build/). Serves /introduction content at / via slug override. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Platform pages (6): architecture, composition, stores, providers, scope, observability — grounded in atomicmemory-core source. HTTP API reference (9): conventions, ingest, search, list-get-delete, consolidate-decay-cap, lessons, audit, config, agents — ported from atomicmemory-core/docs/api-reference.md. Intro + quickstart: value prop, differentiator table, Docker-to-first-search in under 2 minutes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Codex review found three issues:
1. search.md + list-get-delete.md hid the shipped scope/security contract:
- POST /memories/search now documents workspace_id/agent_id/visibility/
agent_scope request fields and the scope + observability response fields
- POST /memories/search/fast request table adds the same scope fields
- GET /memories/list now documents workspace_id/agent_id/source_site/
episode_id query params + the agent_id-required-for-workspace enforcement
2. introduction.md overclaimed AtomicMemory's embedding provider support
(anthropic/google/groq are LLM-only per src/config.ts + src/services/
llm.ts) and oversimplified mem0/letta/zep. Split providers row into
separate embedding/LLM rows; softened competitor claims; added sources.
3. onBrokenMarkdownLinks upgraded from 'warn' to 'throw' via the new
markdown.hooks config path. Build stays green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… on get/delete Codex round-2 review: 1. search.md advertised 'visibility' as a request-time filter, but the route drops it when building MemoryScope (src/routes/memories.ts:531 parses it into WorkspaceContext, then toMemoryScope at :658 constructs the scope without it). Workspace visibility is enforced against each memory's stored visibility column — not caller-provided. Remove it from both request tables and clarify how visibility actually works. 2. list-get-delete.md GET /memories/:id and DELETE /memories/:id only documented user_id, but the routes also accept workspace_id and require agent_id for workspace-scoped reads/deletes. Document the full param set consistent with the list route. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Core now serves memory routes under the /v1 version prefix. Update all quickstart, platform, and HTTP reference pages to match.
…erence (#2) Introduces a dedicated SDK documentation section (20 hand-authored pages) with equal navigational presence to Platform and API Reference. The SDK is framed as a platform utility agnostic to the memory backend — the provider model is the headline, runtime capability inspection is the contract. Structure: overview + quickstart, 7 concept pages (architecture, provider model, capabilities, scopes and identity, storage adapters, embeddings, consent and gating), 7 guides (atomicmemory backend, mem0 backend, custom provider, browser helpers, Node.js server, browser primitives, swapping backends), 3 API reference contract pages (reference overview, MemoryProvider contract, errors), and a cookbook entry for loadKnowledgeBase. Architecture and dataflow diagrams are rendered via @docusaurus/theme-mermaid: high-level SDK architecture, provider classDiagram, ingest sequence, search with domain gating, package with extension probe, storage subsystem, deployment topologies, and the embeddings pipeline. Every diagram is tied to real class/file/method names from the SDK source. Type-level API reference (method signatures, exported types, subpath exports) is deferred to the SDK's existing typedoc pipeline; hand-written pages here cover only the authoring contracts that generated docs cannot. Also: - Replaces "coming soon" text in introduction.md with links to /sdk/overview - Adds an "Using the TypeScript SDK" section to the Core quickstart - Adds memory-provider disambiguation to platform/providers.md - Adds a see-also pointer to platform/scope.md - Deletes docs/api-reference/sdk/coming-soon.md, replaced by a @docusaurus/plugin-client-redirects redirect (/api-reference/sdk/coming-soon -> /sdk/overview) — GitHub Pages compatible, unlike _redirects
…#3) * OpenAPI Phase 5: docusaurus-plugin-openapi-docs + generated artifacts Wires the HTTP API reference to the OpenAPI spec shipped inside @atomicmemory/atomicmemory-core. docusaurus-plugin-openapi-docs generates 29 .mdx pages + sidebar.ts from the spec on every prestart/prebuild; the artifacts are committed so fresh clones render the site without invoking gen first. Deps: - @atomicmemory/atomicmemory-core (file:../Atomicmemory-core for now — needs to switch to a published version ^1.0.x before this branch is merged) - docusaurus-plugin-openapi-docs + docusaurus-theme-openapi-docs docusaurus.config.ts: - register the plugin under id 'openapi', pointing specPath at require.resolve('@atomicmemory/atomicmemory-core/openapi.yaml') so the generator tracks whatever core version is installed - add the theme to themes[] - set docs.docItemComponent='@theme/ApiItem' (required for the generated api.mdx renderers) package.json scripts: - gen:api / clean:api (plugin CLI passthroughs) - prestart + prebuild both run gen:api so local dev and CI build always regenerate from the latest core spec sidebars.ts: - import the plugin-generated sidebar.ts and plug it into apiReferenceSidebar under a "HTTP API" category - keep hand-authored conventions.md as the anchor intro page Deletions: 8 hand-written markdown pages under docs/api-reference/ http/ (ingest, search, list-get-delete, consolidate-decay-cap, lessons, audit, config, agents). Their content was a manual port of atomicmemory-core/docs/api-reference.md; the generated pages replace them 1:1 and drift is no longer possible. Stale-link fixes: - docusaurus.config.ts footer → /api-reference/http/ingest-memory - docs/quickstart.md "Full API reference" link → ingest-memory - docs/sdk/guides/atomicmemory-backend.md table row links → the 5 new per-route slugs (ingest-memory, search-memories, etc.) * Fix Phase 5 CI-unmergeable state + regen idempotence + envelope doc Codex flagged three real issues on the Phase 5 PR: 1. file: dep broke CI / Pages. @atomicmemory/atomicmemory-core pinned to file:../Atomicmemory-core resolves only in this local workspace; deploy.yml's `npm ci` would have failed on GitHub Actions. Fix: vendor core's openapi.yaml into vendor/atomicmemory-core-openapi.yaml and point docusaurus.config.ts at the local file. Removed the @atomicmemory/atomicmemory-core dependency entirely. Add scripts/vendor-core-spec.mjs + `npm run vendor:spec` for pulling a refreshed spec from a newly-installed core package; workflow is: npm install @atomicmemory/atomicmemory-core@<version> npm run vendor:spec npm run regen:api git commit 2. prestart/prebuild didn't actually refresh anything. The plugin's gen-api-docs only writes files that don't already exist, so with the generated .mdx / sidebar.ts committed in the repo, rerunning never picked up upstream spec changes. Fix: add `regen:api` = `clean:api && gen:api`, and switch prestart/prebuild to call regen:api. Every local dev start and every CI build now nukes the previous artifacts before regenerating. 3. conventions.md overstated envelope consistency. The page said "all endpoints return a consistent { error } format" but the generated update-config page already documents richer 400 (with detail + rejected) and 410 (with detail) envelopes. Fix: rewrite the Error responses section to (a) explicitly call the basic { error } shape canonical, (b) spell out the two richer PUT /v1/memories/config envelopes with full JSON examples, and (c) annotate the status table so each row notes which envelope applies. The hand-maintained intro page now matches the generated reference. All three checks pass: clean npm ci works without ../Atomicmemory-core, regen:api refreshes artifacts each run, build still succeeds.
Pin `npm start` and `npm run serve` to port 3013 via the Docusaurus `--port` flag so the dev preview sits on a stable, non-default port. Matches the workspace convention where each service has a fixed local port (core 3050, SDK webapp 3015, etc.).
The Phase 5 install used --legacy-peer-deps, which left some transitive deps (search-insights, docusaurus-plugin-sass, picomatch 2.3.2) missing from the lock. npm ci refuses to install when the lock is out of sync, so CI's 'Deploy Docs' workflow was failing on npm ci. Regenerated the lock with a clean 'rm -rf node_modules package-lock.json && npm install' (no --legacy-peer-deps needed — the peer tree is fine on its own). Verified 'npm ci' succeeds against the new lock.
* docs(sdk): update SDK docs to describe v2 MemoryClient surface
Rewrite the SDK section to describe the current public surface —
MemoryClient, the providers config, and the slim ./browser entry —
instead of the pre-split AtomicMemorySDK/ContextManager shape.
- Overview, quickstart, architecture, provider-model, and all guides
now use MemoryClient; userAccounts / platform / targetDomain
examples are gone.
- Scopes-and-identity drops UserAccountsManager and describes the
Scope type the SDK actually accepts.
- browser-helpers is now "Browser entry", describing the
@atomicmemory/atomicmemory-sdk/browser subpath.
- consent-and-gating and cookbook/knowledge-base are removed — those
features live in the webapp wrapper, not the OSS core.
- Storage / embeddings / api pages touched up for the same rename.
Forward-only: these pages describe what the SDK is today, not a
migration path from any prior shape.
* docs(sdk): fix codex review findings — IngestInput shape, Mem0 config, ingestModes spelling
- swapping-backends migration example now uses the real MemoryIngest
shape (content/kind/metadata), not a non-existent memory field
- quickstart multi-provider example uses pathPrefix (the real field),
not apiStyle (webapp-wrapper-era)
- ingestModes spelling: 'messages' plural matches types.ts
- MemoryProvider.close() clarified — providers can define it but
MemoryClient does not drive teardown
* docs(sdk): fix codex findings round 2 — BaseMemoryProvider template methods + requiredScope/extension-key shapes
- custom-provider example now implements the template-method hooks
(doIngest/doSearch/doGet/doDelete/doList) that BaseMemoryProvider
actually requires, not direct overrides of the public methods
- requiredScope shape corrected everywhere: { default: Array<keyof
Scope>, ingest?: ..., ... } not the old { user: bool, ... } form
- extension capability keys corrected to the real spellings: update,
forget, profile, reflect, batch (previously updater/forgetter/
profiler/reflector/batchOps — those are the TypeScript interface
names, not the capability keys)
- scopes-and-identity + capabilities + memory-provider + both backend
guides updated for consistency
* docs(sdk): finish MemoryClient surface sweep — errors.md + capabilities call site
Last two stale sdk. references:
- errors.md handling example now uses memory.package(request) /
memory.search(request) with the single-arg MemoryClient shape
- atomicmemory-backend.md cache tip now says memory.capabilities()
* docs: add Integrations section — coding agents + frameworks
New top-level Integrations sidebar covering:
- Coding agents (Claude Code, OpenClaw full specs; Codex, Cursor
stubs with working manual-setup blocks)
- Frameworks (Vercel AI SDK, LangChain JS, Mastra, OpenAI Agents
SDK, LangGraph JS — all planned stubs with intended shape)
All coding-agent integrations share a common MCP server
(`@atomicmemory/mcp-server`) exposing memory_search / memory_ingest
/ memory_package, implemented in the sibling Atomicmemory-integrations
repo. Docs describe the intended install surface, config shape, and
tool contracts so implementation can proceed against a fixed spec.
* docs: fix admonition title syntax on Integrations stubs
Docusaurus 3 requires `:::note[Title]` bracket syntax for admonition
titles. The space-separated form (`:::note Planned`) was rendering the
word as plain content instead of a title across all seven planned-
integration stub pages.
* docs: port AtomicMem webapp branding — logos + color palette
- Replace the default Docusaurus logo.svg with logo-atomicmem.svg
(the #3A60E4 icon from Atomicmem-webapp/public/icons). Also ship
logo-full.svg (icon+wordmark) and logo-wordmark.svg.
- Rebuild the Infima primary palette around #3A60E4 with matching
dark-mode shades that mirror how the webapp lightens brand tokens.
- Set body text to #1E252E (webapp primary text) and the global
radius to 0.625rem to match webapp tokens.
- Point the social-card reference at logo-full.svg (the previously
referenced atomicmemory-social-card.png did not exist in static/img).
* docs: use Work Sans + Fira Mono and SVG logo favicon
Match the webapp's font stack (Work Sans for display, Fira Mono for
code) by loading both from Google Fonts via `stylesheets` +
preconnect `headTags`. Repoint `--ifm-font-family-base` and
`--ifm-font-family-monospace` at those families.
Swap the favicon from the Docusaurus default ICO to `img/logo.svg`
(the AtomicMem icon ported earlier) — modern browsers render SVG
favicons natively.
* docs: advertise memory_package consistently + fix schema link
Three review fixes:
- Claude Code intro page called out `ingest / search / trust` as the
tool surface while the table below it correctly listed
memory_package — aligned intro to match.
- OpenClaw MCP-bridge section still named `memory_trust`; swapped to
memory_package.
- "Tool schemas mirror the SDK surface" link pointed at
/sdk/api/memory-provider (the provider authoring contract) instead
of the MemoryClient request/response types. Repointed at
/sdk/api/overview with an explicit callout of IngestInput /
SearchRequest / PackageRequest.
* docs: align integrations with SDK V3 scope + drop dead roadmap links
Scope
- SDK V3 Scope is { user, agent, namespace, thread } — not the
{ user, workspace, agent } model the integration docs described.
- Swept workspace → namespace across claude-code.md, openclaw.md,
and mastra.md. Reflect required scope.user in install snippets.
Roadmap links (P3)
- Every planned-integration page linked to the integrations repo's
/issues page to "track progress." The repo has no issues filed,
so readers landed on an empty list. Removed those dead links and
rephrased the admonitions to explain the doc *is* the spec.
Publishing link (P3)
- The OpenClaw page pointed at `.github/workflows/publish-openclaw.yml`
which does not exist. Rephrased as "will live at" + "not yet wired
up" and kept the repo-root link as context.
* chore: ship pnpm-lock.yaml
I'd been leaving this untracked because the repo already commits
package-lock.json and CI runs `npm ci` (see 6df76ab). Committing
the pnpm lockfile on request; the repo now has both lockfiles,
which can drift. Picking one lockfile and updating CI accordingly
is a follow-up decision.
* chore: remove pnpm-lock.yaml and gitignore it
This repo uses npm — package-lock.json is the source of truth and
.github/workflows/deploy.yml runs `npm ci`. Dropping the pnpm
lockfile I added in 0134848 (ships pnpm-lock.yaml) and gitignoring
it so a stray `pnpm install` cannot resurrect it and drift from the
npm lockfile.
* docs: link integrations to real source + honest status
Now that the integrations repo is public, the docs can point at the
actual committed files instead of hand-waving at "an intended shape."
Overview
- Added a Source column linking to `plugins/claude-code` and
`plugins/openclaw` on the coding-agents table.
- Downgraded status from `✅ Available` to `🔧 Source available` with
a footnote explaining the `@atomicmemory/mcp-server` npx flow
remains gated on the SDK publishing to npm.
- Replaced the fictional `plugins/_template/` contributing sentence
with a real "Contributing" section that links the MCP server and
plugins directories and describes the actual contribution path
(copy the closest plugin, swap the manifest, reuse the server).
Claude Code page
- Rewrote the Status callout with a specific source link and a
pointer at the mcp-server status note.
- Added a "View source" section linking plugin.json, SKILL.md, and
the MCP server package.
OpenClaw page
- Same status rewrite and "View source" section (manifest, skill
files, plugin entry).
…mat) (#9) Follow-up to the redone Codex plugin in Atomicmemory-integrations#5. The earlier Codex plugin used ~/.codex/config.toml; the real plugin format is .codex-plugin/plugin.json + .codex-mcp.json + a marketplace.json manifest (matching how mem0-plugin ships). Rewrite the doc page around that: - Three install options: repo marketplace (recommended), personal marketplace, manual MCP config - Configure section with the env-var surface mirroring packages/mcp-server/src/config.ts - Memory protocol skill section summarizing the shipped SKILL.md (on new task / after significant work / before context loss) - MCP tools table pointing at SDK reference - View source section with direct links to plugin.json, .codex-mcp.json, SKILL.md, and marketplace.example.json - Overview table: Codex row flipped to "🔧 Source available" with the correct install surface label and source link
Matches the same cleanup already on the integrations repo: remove Mem0 mentions from backend-agnostic pitch bullets on each coding-agent page and the overview. Rewrite as "or any other registered MemoryProvider" — same technical story, no third-party naming. Scope is deliberately limited to docs/integrations/**. SDK reference pages, the sdk/guides/mem0-backend.md how-to, and the introduction differentiation table are left alone per direction — those document existing SDK code or are intentional differentiation writing. Kept as-is (config contract, not marketing): - claude-code.md "To use Mem0 as the backend instead, set `\"provider\": \"mem0\"`" — documenting an actual enum value - openclaw.md configSchema snippet enum — mirrors the published manifest - codex.md `# or "mem0"` env comment — same reasoning
Restructures the Claude Code integration page to match the section flow used by docs.mem0.ai/integrations/claude-code: 1. Hero + status callout 2. Overview — 4 numbered value props 3. Prerequisites — core running, API key, CLI installed, shell env 4. Installation — 3 options (Plugin / MCP Only / Manual MCP + Skill) 5. Verify 6. What's Included — comparison table across install options 7. Available MCP Tools 8. Lifecycle Hooks — per-hook subsections referring to shipped scripts in Atomicmemory-integrations#7 9. Example Workflow — cross-session narrative 10. Memory Protocol Skill — summary of the shipped skill content 11. Troubleshooting 12. View source 13. See also Written against shipped behavior — the Lifecycle Hooks section is real now that PR #7 landed hooks/hooks.json + 6 scripts. Each hook subsection links to the exact shipped script for attribution. Dependent: merge Atomicmemory-integrations#7 first so the /plugins/claude-code/hooks and /plugins/claude-code/scripts GitHub links resolve.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Rewrites the Claude Code integration page to match the section flow used by docs.mem0.ai/integrations/claude-code, same principle applied to the Codex doc earlier.
Written against shipped behavior — the full Lifecycle Hooks section describes the 6 scripts landed in Atomicmemory-integrations#7. Each hook subsection links to the exact shipped script for attribution.
Section flow
Test plan