Skip to content

docs: use real ~/.claude/projects/ path in first-run help and README (#996)#1012

Merged
igorls merged 1 commit intodevelopfrom
docs/use-real-claude-projects-path-996
Apr 18, 2026
Merged

docs: use real ~/.claude/projects/ path in first-run help and README (#996)#1012
igorls merged 1 commit intodevelopfrom
docs/use-real-claude-projects-path-996

Conversation

@bensig
Copy link
Copy Markdown
Collaborator

@bensig bensig commented Apr 18, 2026

Summary

Fixes #996.

First-time users who ran mempalace --help saw ~/chats/ — a path that doesn't exist on any machine. Real location where Claude Code writes session JSONL is ~/.claude/projects/<escaped-project-path>/. Three user-visible strings updated.

Change

Three lines across two files:

  • mempalace/cli.py:7 — "Two ways to ingest" help block
  • mempalace/cli.py:25 — Examples block
  • README.md:58 — Quickstart

The website guides (website/guide/mining.md, getting-started.md) still use ~/chats/ as a placeholder for ChatGPT/Slack export scenarios where it remains reasonable. Those can tilt toward Claude Code examples in a follow-up if the maintainers prefer.

Test plan

  • mempalace --help shows ~/.claude/projects/ (no ~/chats/ in output)
  • grep -r "~/chats" mempalace/ README.md returns nothing
  • README Quickstart command copy-paste resolves to a real path on the user's machine

Copy link
Copy Markdown
Member

@igorls igorls left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tested locally (py 3.12, clean worktree on pr-1012):

  • python -c "import mempalace.cli; print(mempalace.cli.__doc__)" shows the new ~/.claude/projects/ strings in both the "Two ways to ingest" block and the Examples block. No ~/chats/ in mempalace/ or README.md after the change.
  • Full test suite: 973 passed.

The fix is scoped exactly to the user-visible first-run strings the issue called out, and the PR body already acknowledges website/guide/mining.md, website/guide/getting-started.md, and examples/convo_import.py as intentional follow-ups — agreed, those can tilt in a separate PR if we want to pivot the guides toward Claude Code examples.

LGTM.

…996)

The CLI help text and README told first-time users to mine from ~/chats/,
a path that doesn't exist on any machine. Real location where Claude
Code writes session JSONL is ~/.claude/projects/<escaped-project-path>/.

Updates three user-visible strings:
- mempalace/cli.py line 7 ("Two ways to ingest" block)
- mempalace/cli.py line 25 (Examples block)
- README.md line 58 (Quickstart)

Website guides (website/guide/mining.md, getting-started.md) still
reference ~/chats/ for ChatGPT/Slack export scenarios where that remains
a valid placeholder. Those can be a separate PR if the maintainers want
to tilt the website examples toward Claude Code specifically.

Fixes #996.
@bensig
Copy link
Copy Markdown
Collaborator Author

bensig commented Apr 18, 2026

Amended to address three code-review findings on the wording:

  1. Dropped the misleading ChatGPT/Slack exports parenthetical at the ~/.claude/projects/ path — those exports aren't in that dir, they live wherever the user downloaded them.
  2. Restored the Claude.ai format mention (normalize._try_claude_ai_json() still handles it).
  3. Narrowed the Examples block to a per-project subdir + --wing so the canonical copy-paste doesn't ingest all Claude Code projects at once.

README Quickstart still uses the broad path (it's the first-run simple case) but now notes scoping with --wing.

@bensig bensig force-pushed the docs/use-real-claude-projects-path-996 branch from df5b6f1 to a2da0d6 Compare April 18, 2026 20:31
@igorls igorls merged commit 8a130fc into develop Apr 18, 2026
6 checks passed
jphein added a commit to jphein/mempalace that referenced this pull request Apr 19, 2026
…uard

Merges MemPalace#990 (RFC 002 spec), MemPalace#1014 (BaseSourceAdapter/PalaceContext scaffolding),
MemPalace#1013 (Layer3.search_raw None guard), MemPalace#1012 (docs), MemPalace#1010 (chromadb >=1.5.4),
and MemPalace#998 (sweeper/tandem transcript safety net).

Fork changes preserved:
- quarantine_stale_hnsw() in chroma.py (guards HNSW/sqlite drift segfault)
- get-then-create instead of get_or_create (guards ChromaDB 1.5.x metadata segfault)
- paginated status() loop (guards SQLite variable limit on large palaces)
- searcher hits-loop, BM25 fallback, _count_in_scope
- .jsonl exempt from JUNK_FILE_SIZE cap (Claude Code transcripts can be large)
- _validate_where() + operator constants taken from upstream

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
igorls added a commit that referenced this pull request Apr 19, 2026
Version bumps across pyproject.toml, mempalace/version.py, README badge,
uv.lock, and plugin manifests (.claude-plugin/*, .codex-plugin/*).

CHANGELOG aligned with main (post-3.3.1) and a new [3.3.2] section added
covering the 11 PRs merged on develop since v3.3.1 — silent-transcript-drop
fix + tandem sweeper (#998), None-metadata guards (#999, #1013),
chromadb ≥1.5.4 for Py 3.13/3.14 (#1010), Windows Unicode (#681),
HNSW quarantine recovery (#1000), PID stacking guard (#1023), doc-path
cleanup (#996, #1012), and RFC 001/002 internal scaffolding (#995, #1014, #990).
@igorls igorls mentioned this pull request Apr 19, 2026
8 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: CLI help and README reference fictional ~/chats/ path instead of real ~/.claude/projects/

2 participants