fix: persist runtime skills + volume consolidation + docs overhaul#13
Merged
fix: persist runtime skills + volume consolidation + docs overhaul#13
Conversation
Skills created during chat (e.g. via Claude Code) are written to ~/.claude/skills/ which resolves to the sessions volume. Previously these were lost on restart because syncSkills() clears the destination first. Now both entrypoint.sh and skills.ts persist non-managed skills back to USER_SKILLS_DIR before wiping the destination. Also restructured entrypoint.sh to resolve ORG_SKILLS_SRC before the persist block so it can correctly identify managed vs runtime skills. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…MEMORY_DIR SDK session state (.claude/) now lives at $MEMORY_DIR/.claude/ instead of a separate SESSIONS_DIR volume. Reduces deployment from 4 volumes to 3 (memory, store, org). SESSIONS_DIR env var is deprecated — a startup warning is printed if set. USER_SKILLS_DIR env var is removed — user skills are always at $MEMORY_DIR/skills/, consistent with the consolidation principle. The runtime-skills persist logic (persistRuntimeSkills) is preserved but updated: comments now reference "syncSkills() clears the destination" instead of the former "sessions volume" rationale. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove /data/sessions volume mount from Dockerfile, docker-compose, Makefile, picoclaw.sh, and e2e test script. entrypoint.sh changes: - SESSION_CLAUDE_DIR derived from MEMORY_DIR instead of hardcoded /data/sessions - USER_SKILLS_SRC derived from MEMORY_DIR (no env var override) - Circular symlink detection for auto-memory when CLAUDE_HOME is inside MEMORY_DIR (merged mode) - Updated comments to remove "sessions volume" references Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Update all docs to reflect 3-volume model (memory, store, org): - Remove SESSIONS_DIR and USER_SKILLS_DIR from env var tables - Remove /data/sessions from volume mount examples and diagrams - Add .claude/ subdirectory to /data/memory descriptions - Add .claude/CLAUDE.md risk note to SKILLS_AND_PERSONA_GUIDE - Update DESIGN_RATIONALE "Why Four Separate Volumes" section - Add volume consolidation entry to CHANGELOG Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
bupao
changed the title
…ence Knowledge extracted from internal analysis documents: SKILLS_AND_PERSONA_GUIDE.md: - Configuration reload timing table (per-request / manual reload / restart) - Runtime-created skills lifecycle (persist-before-clear behavior) - Agent input context format (XML with timezone, sender, timestamps) - [SCHEDULED TASK] prefix auto-injection for task-triggered runs - Persona best practices: trigger conditions, tool priority, degradation strategies, full MCP tool name prefix requirement CLAUDE.md: - Boot sequence diagram (entrypoint.sh → index.ts → Express) - additionalDirectories ≠ skill discovery gotcha Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…oute - Fix Go-Live checklist: :id → /:conversation_id (correct path params) - Move ANTHROPIC_BASE_URL from Required to Optional (SDK has built-in default) - Split "Mounted Volumes" into persistent vs ephemeral tables for clarity - Add note explaining volumes.sessions field is backward-compat alias for .claude/ - Add MEMORY_DIR, STORE_DIR, ASSISTANT_NAME, LOG_LEVEL to CLAUDE.md env table - Remove ANTHROPIC_BASE_URL from secrets checklist (not a secret) - Add code comment in health.ts clarifying sessions field Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Single-page reference covering all env vars, API endpoints, volumes, persona/skills config, MCP servers, and runtime controls. Replaces scattered information across multiple docs with one scannable document. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Merge valuable content from prior team draft: POST /task parameters, SDK internal settings, FAQ (Q1-Q6), and configuration cross-reference table. All references updated for the current 3-volume model. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
bupao
changed the title
Drop the runtime warning for SESSIONS_DIR — the variable is simply removed. Docs updated to say "removed" instead of "deprecated". Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Revert prettier's padded table alignment (excessive --- separators and trailing whitespace) back to compact format. Content unchanged. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
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
1 participant
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
.claude/skills/) are now automatically persisted to$MEMORY_DIR/skills/before the next sync, surviving container restarts. Bothentrypoint.shandsrc/skills.tsimplement the persist-before-clear logic.SESSIONS_DIRentirely. SDK session state (.claude/) now lives insideMEMORY_DIR, reducing deployment from 4 volumes to 3 (memory,store,org).SESSIONS_DIRenv var is deprecated and ignored with a warning.docs/CONFIGURATION_REFERENCE.mdwith FAQ, task parameters, cross-reference table. Updated all docs for 3-volume model.Changes
Code (4 files)
src/config.ts— RemoveSESSIONS_DIRexport, add deprecation warningsrc/index.ts— UseMEMORY_DIR/.claudeinstead ofSESSIONS_DIRsrc/skills.ts— Persist runtime-created skills + useMEMORY_DIRfor destinationsrc/routes/health.ts— Health checksessionsfield now checksMEMORY_DIR/.claudeContainer & deployment (5 files)
Dockerfile— Remove/data/sessions, create/data/memory/.claude/skillsentrypoint.sh— Runtime skill persist logic, auto-memory circular symlink guarddocker-compose.yml— Remove sessions volumeMakefile— Remove sessions volume referencespicoclaw.sh— Remove sessions volume mountTests (3 files)
src/skills.test.ts— Tests for runtime skill persistence and shadow detectionsrc/entrypoint.test.ts— Test for merged-mode auto-memory symlink skipscripts/e2e-test.sh— Update paths for 3-volume modelDocumentation (8 files)
docs/CONFIGURATION_REFERENCE.md— New consolidated config reference (12 sections)docs/SERVERLESS_API_DEPLOYMENT_GUIDE.md— Fix audit findings, update volumesdocs/DESIGN_RATIONALE.md— Update to 3-volume rationaledocs/SECURITY.md— Update filesystem boundary tabledocs/SKILLS_AND_PERSONA_GUIDE.md— Add.claude/to memory structureCLAUDE.md— Add missing env vars, update volume tableCHANGELOG.md— Volume consolidation entryREADME.md— Update quick-start for 3-volume modelMigration (existing deployments)
New deployments need only
memory+store(+ optionalorg).Test plan
npm run buildpassesnpm test— 52/53 pass (1 flaky socket hang up in server.test.ts, pre-existing)npm run format:checkpasses./scripts/e2e-test.shwith Docker (updated paths)SESSIONS_DIRdeprecation warning appears when set🤖 Generated with Claude Code