feat: move entity storage to .kaizen/ and add Kaizen Lite guide - #67
Merged
Conversation
Move entity storage from .claude/entities.json to .kaizen/entities.json so the plugin has its own dedicated workspace directory. Add KAIZEN_LITE.md documenting the lightweight plugin-only mode that requires no vector DB, MCP servers, or API keys. Includes a walkthrough example showing the learn-then-recall loop across two sessions and a tradeoffs section comparing Lite with Full Kaizen.
📝 WalkthroughWalkthroughAdds Kaizen Lite documentation and standardizes entity storage paths from Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
plugins/kaizen/skills/learn/scripts/save_entities.py (1)
53-66:⚠️ Potential issue | 🟠 MajorNo backward-compatibility fallback for existing
.claude/entities.jsondataUsers who ran the plugin before this PR have entities in
.claude/entities.json. After upgrading, bothfind_entities_file()here and inretrieve_entities.pycompletely ignore that path — entities are silently inaccessible and the next/kaizen:learncreates a fresh.kaizen/entities.json. There is no runtime warning, no automatic migration, and no mention of a manual migration step in any of the updated docs.🛡️ Suggested one-time migration fallback
for loc in locations: if loc and Path(loc).exists(): return Path(loc).resolve() + # One-time migration: check old .claude/ path and notify user + for old_base in [os.environ.get("CLAUDE_PROJECT_ROOT", ""), "."]: + old_path = Path(old_base) / ".claude" / "entities.json" + if old_path.exists(): + print( + f"[kaizen] Found entities at deprecated path {old_path}. " + f"Move it to .kaizen/entities.json or set KAIZEN_ENTITIES_FILE.", + file=sys.stderr, + ) + break + return None🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/kaizen/skills/learn/scripts/save_entities.py` around lines 53 - 66, The code currently ignores legacy ".claude/entities.json" causing silent data loss; update find_entities_file() in save_entities.py to include the legacy path (".claude/entities.json") in the locations list (and do the same lookup in retrieve_entities.py), and when that legacy file is found perform a one-time migration: copy/move it into the new location (e.g., ".kaizen/entities.json") and emit a process/log warning that a migration occurred so users aren’t surprised. Ensure you use Path.resolve(), handle IO exceptions, and preserve file permissions and contents during the migration so both find_entities_file() and retrieve_entities.py can transparently use the migrated file.
🧹 Nitpick comments (2)
plugins/kaizen/skills/learn/scripts/save_entities.py (1)
74-77: Stale variable nameclaude_dirnow refers to.kaizen/The variable was carried over from the old
.claude/path. Rename it tokaizen_dirto match the new directory.♻️ Rename stale variable
- claude_dir = Path(project_root) / ".kaizen" + kaizen_dir = Path(project_root) / ".kaizen" else: # Fall back to current directory's .kaizen/ - claude_dir = Path(".kaizen") + kaizen_dir = Path(".kaizen") - claude_dir.mkdir(parents=True, exist_ok=True) - return (claude_dir / "entities.json").resolve() + kaizen_dir.mkdir(parents=True, exist_ok=True) + return (kaizen_dir / "entities.json").resolve()🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/kaizen/skills/learn/scripts/save_entities.py` around lines 74 - 77, The variable name claude_dir is stale and should be renamed to kaizen_dir wherever it's defined and used (e.g., the assignment clauses that set Path(project_root) / ".kaizen" and Path(".kaizen")), so update the variable name in save_entities.py to kaizen_dir and adjust all subsequent references to use kaizen_dir instead of claude_dir to match the new .kaizen directory name.plugins/kaizen/skills/recall/scripts/retrieve_entities.py (1)
67-74: Duplicate fallback entry whenCLAUDE_PROJECT_ROOTis unset
os.path.join("", ".kaizen/entities.json")evaluates to".kaizen/entities.json", making entries at index 0 and 1 identical when the env var is absent. The same pattern exists insave_entities.pylines 53–57.♻️ Filter out the empty-prefix entry
locations = [ # Project root from Claude Code - os.path.join(os.environ.get("CLAUDE_PROJECT_ROOT", ""), ".kaizen/entities.json"), + *( + [os.path.join(os.environ["CLAUDE_PROJECT_ROOT"], ".kaizen/entities.json")] + if os.environ.get("CLAUDE_PROJECT_ROOT") + else [] + ), # Current working directory ".kaizen/entities.json", # Plugin-relative path (fallback) str(Path(__file__).parent.parent / "entities.json"), ]🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/kaizen/skills/recall/scripts/retrieve_entities.py` around lines 67 - 74, The locations list includes os.path.join(os.environ.get("CLAUDE_PROJECT_ROOT", ""), ".kaizen/entities.json") which becomes ".kaizen/entities.json" when CLAUDE_PROJECT_ROOT is unset, duplicating the second entry; update the code that builds the locations list in retrieve_entities.py (and mirror the same change in save_entities.py) to only include the joined path when os.environ.get("CLAUDE_PROJECT_ROOT") is truthy (or alternatively build the list and remove duplicates while preserving order), so the entries in variable locations are unique.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@KAIZEN_LITE.md`:
- Around line 46-79: Add the Markdown language specifier "text" to both fenced
conversation transcript blocks (the Session 1 and Session 2 code fences) so they
start with ```text instead of ```; update the first fenced block containing the
You/Claude transcript (the block beginning with "You: Tell me the distances...")
and the second transcript block later in the file to satisfy markdownlint MD040.
---
Outside diff comments:
In `@plugins/kaizen/skills/learn/scripts/save_entities.py`:
- Around line 53-66: The code currently ignores legacy ".claude/entities.json"
causing silent data loss; update find_entities_file() in save_entities.py to
include the legacy path (".claude/entities.json") in the locations list (and do
the same lookup in retrieve_entities.py), and when that legacy file is found
perform a one-time migration: copy/move it into the new location (e.g.,
".kaizen/entities.json") and emit a process/log warning that a migration
occurred so users aren’t surprised. Ensure you use Path.resolve(), handle IO
exceptions, and preserve file permissions and contents during the migration so
both find_entities_file() and retrieve_entities.py can transparently use the
migrated file.
---
Nitpick comments:
In `@plugins/kaizen/skills/learn/scripts/save_entities.py`:
- Around line 74-77: The variable name claude_dir is stale and should be renamed
to kaizen_dir wherever it's defined and used (e.g., the assignment clauses that
set Path(project_root) / ".kaizen" and Path(".kaizen")), so update the variable
name in save_entities.py to kaizen_dir and adjust all subsequent references to
use kaizen_dir instead of claude_dir to match the new .kaizen directory name.
In `@plugins/kaizen/skills/recall/scripts/retrieve_entities.py`:
- Around line 67-74: The locations list includes
os.path.join(os.environ.get("CLAUDE_PROJECT_ROOT", ""), ".kaizen/entities.json")
which becomes ".kaizen/entities.json" when CLAUDE_PROJECT_ROOT is unset,
duplicating the second entry; update the code that builds the locations list in
retrieve_entities.py (and mirror the same change in save_entities.py) to only
include the joined path when os.environ.get("CLAUDE_PROJECT_ROOT") is truthy (or
alternatively build the list and remove duplicates while preserving order), so
the entries in variable locations are unique.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
KAIZEN_LITE.mdREADME.mdplugins/kaizen/README.mdplugins/kaizen/skills/learn/SKILL.mdplugins/kaizen/skills/learn/scripts/save_entities.pyplugins/kaizen/skills/recall/SKILL.mdplugins/kaizen/skills/recall/scripts/retrieve_entities.py
Rename claude_dir to kaizen_dir in save_entities.py to match the .kaizen directory, add text language specifier to KAIZEN_LITE.md fenced blocks, and guard CLAUDE_PROJECT_ROOT locations entry so it is only included when the env var is set (preventing a duplicate .kaizen/entities.json path).
There was a problem hiding this comment.
🧹 Nitpick comments (1)
plugins/kaizen/skills/recall/scripts/retrieve_entities.py (1)
74-76: UsePathfor consistency with the rest offind_entities_file.Line 72 already builds paths with
pathlib, and every entry is wrapped inPath()at line 78. Mixingos.path.joinwith an embedded forward slash here is a minor style inconsistency, even thoughPath(loc).exists()normalises separators on all platforms.♻️ Proposed refactor
if project_root: # Project root from Claude Code (prepend so it's checked first) - locations.insert(0, os.path.join(project_root, ".kaizen/entities.json")) + locations.insert(0, str(Path(project_root) / ".kaizen" / "entities.json"))🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/kaizen/skills/recall/scripts/retrieve_entities.py` around lines 74 - 76, The code mixes os.path.join with pathlib in find_entities_file: replace the os.path.join usage so the project-root path is constructed with Path—e.g., build a Path from project_root and append ".kaizen/entities.json" (or using / to join) before inserting into locations—so the inserted item is a Path instance consistent with the other entries referenced later (look for locations.insert(0, ...) and project_root).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@plugins/kaizen/skills/recall/scripts/retrieve_entities.py`:
- Around line 74-76: The code mixes os.path.join with pathlib in
find_entities_file: replace the os.path.join usage so the project-root path is
constructed with Path—e.g., build a Path from project_root and append
".kaizen/entities.json" (or using / to join) before inserting into locations—so
the inserted item is a Path instance consistent with the other entries
referenced later (look for locations.insert(0, ...) and project_root).
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
KAIZEN_LITE.mdplugins/kaizen/skills/learn/scripts/save_entities.pyplugins/kaizen/skills/recall/scripts/retrieve_entities.py
🚧 Files skipped from review as they are similar to previous changes (2)
- plugins/kaizen/skills/learn/scripts/save_entities.py
- KAIZEN_LITE.md
jayaramkr
approved these changes
Feb 23, 2026
This was referenced Feb 26, 2026
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
3 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.
Move entity storage from .claude/entities.json to .kaizen/entities.json so the plugin has its own dedicated workspace directory.
Add KAIZEN_LITE.md documenting the lightweight plugin-only mode that requires no vector DB, MCP servers, or API keys. Includes a walkthrough example showing the learn-then-recall loop across two sessions and a tradeoffs section comparing Lite with Full Kaizen.
For #66
Summary by CodeRabbit
Documentation
Chores