Move learning journal out of .claude/ to a durable, agent-neutral global store

[ktaletsk]

Problem

The learning journal currently lives at .claude/learning-journal.md inside each project. This has caused real data loss and excludes non-Claude agents:

• It gets destroyed. .claude/ is commonly untracked or gitignored. A git clean, a session rewind, or a branch switch can wipe the journal with no recovery. This has already happened to at least one user (an opencode session rewind nuked an untracked .claude/ journal).
• It's Claude-specific. Hardcoding .claude/ quietly excludes the opencode / Cursor / other-agent users that the multi-agent npx skills installer otherwise reaches.
• It's siloed per-repo. Personal learning progress is scattered across N project directories, with no way to ever see it in aggregate (blocks any future dashboard / cross-repo review queue).

Proposed direction

Move the default journal to a global per-user store, keyed by repo identity, at an XDG path:

~/.local/share/learn-codebase/<repo-key>/journal.md

• <repo-key> derives from the git remote URL when present (stable across machines/clones), falling back to the repository toplevel path for repos with no remote.
• Honors $XDG_DATA_HOME when set; falls back to ~/.local/share (and the platform equivalent on macOS/Windows).

This mirrors how spaced-repetition tools (e.g. Anki) store personal learning state — centrally, not scattered per-project.

Why this location

• Durable — survives git clean, session rewinds, branch switches, and .gitignore. The data loss can't recur.
• Agent-neutral — drops the .claude/ coupling so opencode/Cursor/etc. users get a real home. Lets us market true multi-agent support.
• Aggregatable — one store across all repos is the natural substrate for a future status / dashboard command and a cross-repo spaced-review queue (see follow-up issues).

Opt-in: keep it in the repo

For people who want the journal to travel with a fork or be shared, support an --in-repo (or config) mode that writes to a tracked, neutral path in the project. Global store remains the default.

Open questions

• Repo-key scheme — remote URL vs. toplevel path. Normalization (strip .git, ssh-vs-https, casing)? What about monorepos or multiple worktrees of the same remote?
• Migration — auto-detect an existing .claude/learning-journal.md on first run and offer to move/copy it to the global store, so current users don't lose history.
• Discoverability — a global store is "out of sight." Do we print the journal path at session start, and/or provide a command to locate/open it?
• Cross-machine sync — global store doesn't travel with a clone. Acceptable for personal state (user backs up home dir), or do we document a sync recommendation?
• Platform paths — confirm XDG fallback behavior on macOS and Windows.
• Config surface — env var, skill config, or both for choosing global vs. in-repo and overriding the base dir.

Scope of change

• SKILL.md — the existence-check / creation logic (currently checks and writes .claude/learning-journal.md).
• README.md — update the journal-location description and the data-durability story.
• .gitignore — the learning-journal.md ignore entry becomes mostly moot for the default path.

Feedback welcome on the repo-key scheme and migration UX before implementation.

[ktaletsk]

On migration

Rather than building auto-detect/move logic into SKILL.md (which adds branching to the startup path and has to handle edge cases forever), the cleanest one-time migration is a copy-paste prompt in the README that the user hands to their agent. The agent already has filesystem + git access, so it can do the move correctly for whatever location scheme we land on, and the prompt simply disappears from people's workflow once they've run it.

Benefits:

• Zero permanent complexity in the skill — migration is a one-shot, not a code path we maintain.
• Agent-neutral by construction (works in Claude Code, opencode, Cursor — whatever the user runs).
• Self-correcting — if the global-store path scheme changes later, we just update the README snippet.

Draft prompt for the README

Migrate my learn-codebase journal to the new global location.

1. Look for an existing journal at `.claude/learning-journal.md` in this repo
   (also check `.agents/`, `.opencode/`, `.cursor/` if not found there).
   If none exists, tell me there's nothing to migrate and stop.
2. Compute the new path:
   - base = $XDG_DATA_HOME if set, else ~/.local/share
   - repo-key = the git remote `origin` URL, normalized (strip a trailing
     `.git`, lowercase the host). If there's no remote, use the absolute
     path of the repo's toplevel directory.
   - destination = <base>/learn-codebase/<repo-key>/journal.md
3. Create the destination directory, move the journal there (don't overwrite
   an existing destination — if one exists, show me both and ask).
4. Print the old and new paths so I can confirm, and remind me the old
   `.claude/` copy is gone.

Open points for the snippet

• Whether to move vs. copy by default. Move is cleaner (no stale duplicate to confuse the skill later), but a nervous first-time user might prefer copy + manual delete. Leaning move-with-confirmation.
• The repo-key normalization rules here must be identical to whatever the skill itself uses, or the skill won't find the migrated journal. That's an argument for nailing down the repo-key scheme (the other open question) first, then deriving this snippet from it.
• We could ship two snippets — a "just do it" one-liner and the verbose version above — for different risk appetites.

[ktaletsk]

Superset design proposed in #3 — organize the global store as a loosely-linked Obsidian vault (journal + mental-model map + gotchas), with the location decided here as the default vault root. This issue keeps ownership of the repo-key scheme and migration mechanics; #3 owns the vault layout, config file, and Obsidian conventions. The two should land together.

[ktaletsk]

Decision: repo-key scheme

Use the path-slug encoding that Claude Code already uses for ~/.claude/projects/ — the absolute path with separators replaced by dashes. Familiar to users, no git dependency, deterministic, filesystem-safe.

Rule

1. Resolve the repo root, not the cwd:
   • In a git repo: git rev-parse --show-toplevel.
   • Not a git repo: the current working directory.
   • (Keying on the root means running from src/, tests/, etc. all resolve to the same journal — keying on cwd would split history per-subdirectory.)
2. Encode the resulting absolute path by replacing / and . with -. Mirror Claude Code's exact transform so the slugs match what users already see.

Example: /Users/ktaletsk/git/learn-codebase → -Users-ktaletsk-git-learn-codebase

Tradeoffs (accepted)

• Not stable across machines / clone paths. A clone at a different path → a different key. This is fine: the journal is personal, per-machine state and the default vault root (~/.local/share/learn-codebase) isn't synced or committed anyway. We're not trying to dedupe across machines.
• Moving the repo on disk changes the key → the old vault folder is orphaned. Mitigation: a small "relocate" path in the migration prompt / future command that detects a renamed root and moves the folder. Low-frequency event.
• Git worktrees each have a distinct toplevel → distinct keys. Acceptable (arguably correct — separate working contexts).

Supersedes

This replaces the earlier "git remote URL, normalized" proposal in the issue body. Remote-based keys would buy cross-machine stability we don't actually need here, at the cost of normalization headaches (ssh vs https, casing, trailing .git, repos with no remote). Path-slug is simpler and matches existing user mental models.