karjimut 2.0.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. karjimut-2.0.2/LICENSE +21 -0
  2. karjimut-2.0.2/PKG-INFO +172 -0
  3. karjimut-2.0.2/README.md +150 -0
  4. karjimut-2.0.2/karjimut.egg-info/PKG-INFO +172 -0
  5. karjimut-2.0.2/karjimut.egg-info/SOURCES.txt +45 -0
  6. karjimut-2.0.2/karjimut.egg-info/dependency_links.txt +1 -0
  7. karjimut-2.0.2/karjimut.egg-info/entry_points.txt +3 -0
  8. karjimut-2.0.2/karjimut.egg-info/requires.txt +12 -0
  9. karjimut-2.0.2/karjimut.egg-info/top_level.txt +1 -0
  10. karjimut-2.0.2/pyproject.toml +71 -0
  11. karjimut-2.0.2/setup.cfg +4 -0
  12. karjimut-2.0.2/src/.env.example +55 -0
  13. karjimut-2.0.2/src/__init__.py +16 -0
  14. karjimut-2.0.2/src/archive_manager.py +605 -0
  15. karjimut-2.0.2/src/assets/karjimut.ico +0 -0
  16. karjimut-2.0.2/src/assets/karjimut_banner.png +0 -0
  17. karjimut-2.0.2/src/assets/karjimut_logo.png +0 -0
  18. karjimut-2.0.2/src/config.py +229 -0
  19. karjimut-2.0.2/src/consolidator.py +415 -0
  20. karjimut-2.0.2/src/data/gui_language.json +3 -0
  21. karjimut-2.0.2/src/db.py +418 -0
  22. karjimut-2.0.2/src/embedding.py +231 -0
  23. karjimut-2.0.2/src/fts_search.py +632 -0
  24. karjimut-2.0.2/src/gui/__init__.py +3 -0
  25. karjimut-2.0.2/src/gui/app_gui.py +554 -0
  26. karjimut-2.0.2/src/gui/i18n.py +310 -0
  27. karjimut-2.0.2/src/gui/key_detector.py +469 -0
  28. karjimut-2.0.2/src/gui/onboarding_dialog.py +413 -0
  29. karjimut-2.0.2/src/gui/project_dialogs.py +178 -0
  30. karjimut-2.0.2/src/gui/shell_layout.py +653 -0
  31. karjimut-2.0.2/src/gui/tab_antrean.py +433 -0
  32. karjimut-2.0.2/src/gui/tab_ktp.py +370 -0
  33. karjimut-2.0.2/src/gui/tab_settings.py +672 -0
  34. karjimut-2.0.2/src/gui/tab_solusi.py +580 -0
  35. karjimut-2.0.2/src/gui/theme.py +32 -0
  36. karjimut-2.0.2/src/idle_watcher.py +222 -0
  37. karjimut-2.0.2/src/ktp_manager.py +415 -0
  38. karjimut-2.0.2/src/llm_distiller.py +265 -0
  39. karjimut-2.0.2/src/log_parser.py +496 -0
  40. karjimut-2.0.2/src/mcp_server.py +522 -0
  41. karjimut-2.0.2/src/rules_template/.cursorrules +37 -0
  42. karjimut-2.0.2/src/rules_template/antigravity_rules.md +40 -0
  43. karjimut-2.0.2/src/run.py +386 -0
  44. karjimut-2.0.2/src/services.py +378 -0
  45. karjimut-2.0.2/src/tokenizer_utils.py +245 -0
  46. karjimut-2.0.2/tests/test_unit_core.py +775 -0
  47. karjimut-2.0.2/tests/test_v2_features.py +503 -0
karjimut-2.0.2/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Naufal Arhab Fadhil Muhammad
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,172 @@
1
+ Metadata-Version: 2.4
2
+ Name: karjimut
3
+ Version: 2.0.2
4
+ Summary: The Autonomous Long-Term Memory Engine for AI Coding Agents
5
+ Author: Naufal Arhab Fadhil Muhammad
6
+ License-Expression: MIT
7
+ Requires-Python: >=3.10
8
+ Description-Content-Type: text/markdown
9
+ License-File: LICENSE
10
+ Requires-Dist: mcp<2.0.0,>=1.2.0
11
+ Requires-Dist: tiktoken>=0.7.0
12
+ Requires-Dist: python-dotenv>=1.0.0
13
+ Requires-Dist: httpx>=0.27.0
14
+ Requires-Dist: customtkinter>=5.2.0
15
+ Requires-Dist: sqlite-vec>=0.1.6
16
+ Requires-Dist: fastembed>=0.9.0
17
+ Requires-Dist: numpy>=1.21.0
18
+ Provides-Extra: dev
19
+ Requires-Dist: pytest>=8.0.0; extra == "dev"
20
+ Requires-Dist: ruff>=0.4.0; extra == "dev"
21
+ Dynamic: license-file
22
+
23
+ <p align="center">
24
+ <img src="sleep-mcp/assets/karjimut_banner.png" alt="Karjimut Banner" width="720" style="border-radius: 16px;" />
25
+ </p>
26
+
27
+ <h1 align="center">Karjimut</h1>
28
+
29
+ <p align="center">
30
+ <strong>The Autonomous Long-Term Memory Engine for AI Coding Agents</strong><br>
31
+ <em>Stop LLM Amnesia. Cut Token Costs by up to 90%. Keep Cursor, Claude Code, and Antigravity Aligned Forever.</em>
32
+ </p>
33
+
34
+ <p align="center">
35
+ <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
36
+ <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-1.2.0%2B-green.svg" alt="MCP Spec"></a>
37
+ <a href="https://pypi.org/project/karjimut/"><img src="https://img.shields.io/pypi/v/karjimut.svg?color=blue" alt="PyPI Version"></a>
38
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
39
+ <a href="https://github.com/Arapemula/Karjimut"><img src="https://img.shields.io/badge/PRs-Welcome-orange.svg" alt="PRs Welcome"></a>
40
+ </p>
41
+
42
+
43
+ ---
44
+
45
+ ## 💡 The Problem with Modern AI Coding Agents
46
+
47
+ Whether you use **Cursor**, **Claude Code**, **Antigravity IDE**, **Windsurf**, or **Cline**, long-term projects always hit three painful walls:
48
+
49
+ 1. 💸 **Context Window Bloat & Cost Explosions**: As sessions grow, raw conversation logs and messy trial-and-error traces accumulate, burning millions of tokens and draining your API budget.
50
+ 2. 🧠 **Context Rot & Session Amnesia**: Start a fresh session or let compaction trigger, and your agent instantly forgets your core architecture rules, directory structure, and repeats the exact same bugs it spent two hours solving yesterday.
51
+ 3. 🏝️ **Developer Memory Isolation**: Your AI agent's hard-won discoveries on your machine remain trapped locally—your teammates' agents will step on the exact same landmines.
52
+
53
+ **Karjimut** solves all three permanently through a **Two-Tier Bio-Inspired Memory Architecture** powered by the **Model Context Protocol (MCP)** and **Autonomous Idle-Phase Consolidation (Sleep Cycle)**.
54
+
55
+ ---
56
+
57
+ ## ⚡ Quick Start (Ready in 60 Seconds)
58
+
59
+ ### 1. Install Karjimut
60
+ Run this single command in your terminal:
61
+
62
+ ```bash
63
+ # Recommended (Official PyPI package)
64
+ pip install karjimut
65
+ ```
66
+
67
+ *Or install directly from GitHub Releases:*
68
+ ```bash
69
+ pip install https://github.com/Arapemula/Karjimut/releases/download/v2.0.2/karjimut-2.0.2-py3-none-any.whl
70
+ ```
71
+
72
+ *(Or run instantly without installation using [uv](https://github.com/astral-sh/uv): `uvx karjimut`)*
73
+
74
+ ### 2. Connect to Your Favorite AI IDE
75
+ Add Karjimut to your IDE's MCP configuration (`mcp_config.json` in Cursor, Antigravity, Claude Desktop, or Windsurf):
76
+
77
+ ```json
78
+ {
79
+ "mcpServers": {
80
+ "karjimut": {
81
+ "command": "karjimut",
82
+ "args": ["mcp"]
83
+ }
84
+ }
85
+ }
86
+ ```
87
+
88
+ ### 3. Drop in the Vibecoder Rule
89
+ Copy [`.cursorrules`](.cursorrules) (for Cursor/Windsurf) or [`GEMINI.md`](GEMINI.md) (for Antigravity) into the root of your project workspace.
90
+
91
+ **That's it!** Your AI agent will now autonomously retain memory, recall bug fixes, and synchronize with your team without you ever having to micro-manage it.
92
+
93
+ ---
94
+
95
+ ## 🖥️ Native Desktop Dashboard
96
+
97
+ Prefer a visual control center? Simply open your terminal and type:
98
+
99
+ ```bash
100
+ karjimut
101
+ ```
102
+
103
+ <p align="center">
104
+ <img src="sleep-mcp/assets/karjimut_logo.png" alt="Karjimut Desktop App" width="120" />
105
+ </p>
106
+
107
+ Karjimut includes a modern, high-performance desktop application built with CustomTkinter:
108
+ - **1-Column Smart Onboarding**: Automatically detects your API keys (Google Gemini, Groq, OpenRouter, Claude, OpenAI) or operates in 100% offline rule-based mode.
109
+ - **Elastic Core Editor**: View and fine-tune your project's active identity and mandatory rules, complete with a 1-click rollback mechanism.
110
+ - **Proven Solution Vault**: Search, curate, and review distilled bug resolutions.
111
+ - **Real-Time Sustainability Analytics**: Live tracking of token savings, raw vs. compressed token efficiency, and AI retention metrics.
112
+
113
+ ---
114
+
115
+ ## 🚀 Key Features
116
+
117
+ ### 🧠 Two-Tier Bio-Inspired Memory
118
+ * **Tier 1: Elastic Project Core (Lapis 1)**: Holds your tech stack, core directory layout, and non-negotiable architecture rules. Always compressed, deduplicated, and instant ($O(1)$ overhead at session start).
119
+ * **Tier 2: On-Demand Solution Vault (Lapis 2)**: Zero token cost during normal coding! Solutions to tricky bugs are retrieved on-demand only when a matching error or stack trace occurs.
120
+
121
+ ### 🌙 Autonomous Sleep Cycle (Idle Consolidation)
122
+ During coding sessions, your agent leaves lightweight milestone notes in an asynchronous queue. When you take a coffee break ($\ge 5$ minutes of inactivity), Karjimut's background daemon activates the **Sleep Cycle**—distilling raw logs, updating core rules, and archiving proven solutions into persistent memory.
123
+
124
+ ### 🤝 Multi-Team Git Synchronization
125
+ Karjimut serializes project memory into clean, git-friendly `.karjimut/team_memory.json` files. When you push and pull via Git, your entire team's AI agents automatically inherit everyone's bug fixes and updated rules—completely free of binary database merge conflicts.
126
+
127
+ ### 🔍 High-Precision Hybrid Search
128
+ Combines lexical keyword matching (for exact error codes like `SQLITE_BUSY` or `#nextjs-15`) with 384-dimensional semantic vector embeddings (`BAAI/bge-small-en-v1.5` via CPU-accelerated ONNX + bilingual ID–EN technical synonym expansion & offline feature-hashing fallback) using Reciprocal Rank Fusion (RRF).
129
+
130
+ ### 🤖 100% Autonomous (Zero-Prompt Vibecoder Protocol)
131
+ You don't need to remind your AI agent to use Karjimut. With the workspace rules attached, the agent operates autonomously:
132
+ 1. **At Session Start**: Automatically fetches the latest Project Core and imports any new team memory.
133
+ 2. **During Coding**: Automatically checkpoints progress and technical rules after completing features.
134
+ 3. **When Errors Strike**: Automatically searches the Solution Vault for a one-shot fix before wasting tokens on hallucinated trial-and-error.
135
+
136
+ ---
137
+
138
+ ## 📂 Repository Structure
139
+
140
+ ```text
141
+ Karjimut/
142
+ |-- README.md # Official product documentation & Quick Start
143
+ |-- GEMINI.md # Autonomous Vibecoder Rule (Antigravity IDE)
144
+ |-- .cursorrules # Autonomous Vibecoder Rule (Cursor & Windsurf)
145
+ |-- .agents/rules/sleep-mcp-auto.md # Universal Agent Bootstrap Rule
146
+ |-- sleep-mcp/
147
+ |-- assets/ # Official brand logos, banners, and app icons
148
+ | |-- karjimut_banner.png
149
+ | |-- karjimut_logo.png
150
+ | |-- karjimut.ico
151
+ |-- rules_template/ # Starter templates for new workspaces
152
+ |-- .cursorrules
153
+ |-- antigravity_rules.md
154
+ ```
155
+
156
+ > **Distribution Architecture:**
157
+ > Karjimut is engineered as a high-performance, standalone package. The core engine (MCP server, native GUI, SQLite WAL vector store, and background watcher) is delivered directly via verified binary packages.
158
+
159
+ ---
160
+
161
+ ## 🛡️ Privacy & Local-First Philosophy
162
+
163
+ - **Zero Telemetry**: Karjimut does not track your keystrokes, projects, or personal data.
164
+ - **Local Storage**: All databases, cache, and vector embeddings reside locally on your machine in SQLite WAL mode.
165
+ - **Your Keys, Your Choice**: Use your own API keys, run local Ollama models, or utilize the 100% offline rule-based distiller.
166
+
167
+ ---
168
+
169
+ ## 📄 License
170
+
171
+ Karjimut is open-source software licensed under the **[MIT License](LICENSE)**.
172
+ Copyright © 2026 **Naufal Arhab Fadhil Muhammad**. All rights reserved.
@@ -0,0 +1,150 @@
1
+ <p align="center">
2
+ <img src="sleep-mcp/assets/karjimut_banner.png" alt="Karjimut Banner" width="720" style="border-radius: 16px;" />
3
+ </p>
4
+
5
+ <h1 align="center">Karjimut</h1>
6
+
7
+ <p align="center">
8
+ <strong>The Autonomous Long-Term Memory Engine for AI Coding Agents</strong><br>
9
+ <em>Stop LLM Amnesia. Cut Token Costs by up to 90%. Keep Cursor, Claude Code, and Antigravity Aligned Forever.</em>
10
+ </p>
11
+
12
+ <p align="center">
13
+ <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
14
+ <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-1.2.0%2B-green.svg" alt="MCP Spec"></a>
15
+ <a href="https://pypi.org/project/karjimut/"><img src="https://img.shields.io/pypi/v/karjimut.svg?color=blue" alt="PyPI Version"></a>
16
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
17
+ <a href="https://github.com/Arapemula/Karjimut"><img src="https://img.shields.io/badge/PRs-Welcome-orange.svg" alt="PRs Welcome"></a>
18
+ </p>
19
+
20
+
21
+ ---
22
+
23
+ ## 💡 The Problem with Modern AI Coding Agents
24
+
25
+ Whether you use **Cursor**, **Claude Code**, **Antigravity IDE**, **Windsurf**, or **Cline**, long-term projects always hit three painful walls:
26
+
27
+ 1. 💸 **Context Window Bloat & Cost Explosions**: As sessions grow, raw conversation logs and messy trial-and-error traces accumulate, burning millions of tokens and draining your API budget.
28
+ 2. 🧠 **Context Rot & Session Amnesia**: Start a fresh session or let compaction trigger, and your agent instantly forgets your core architecture rules, directory structure, and repeats the exact same bugs it spent two hours solving yesterday.
29
+ 3. 🏝️ **Developer Memory Isolation**: Your AI agent's hard-won discoveries on your machine remain trapped locally—your teammates' agents will step on the exact same landmines.
30
+
31
+ **Karjimut** solves all three permanently through a **Two-Tier Bio-Inspired Memory Architecture** powered by the **Model Context Protocol (MCP)** and **Autonomous Idle-Phase Consolidation (Sleep Cycle)**.
32
+
33
+ ---
34
+
35
+ ## ⚡ Quick Start (Ready in 60 Seconds)
36
+
37
+ ### 1. Install Karjimut
38
+ Run this single command in your terminal:
39
+
40
+ ```bash
41
+ # Recommended (Official PyPI package)
42
+ pip install karjimut
43
+ ```
44
+
45
+ *Or install directly from GitHub Releases:*
46
+ ```bash
47
+ pip install https://github.com/Arapemula/Karjimut/releases/download/v2.0.2/karjimut-2.0.2-py3-none-any.whl
48
+ ```
49
+
50
+ *(Or run instantly without installation using [uv](https://github.com/astral-sh/uv): `uvx karjimut`)*
51
+
52
+ ### 2. Connect to Your Favorite AI IDE
53
+ Add Karjimut to your IDE's MCP configuration (`mcp_config.json` in Cursor, Antigravity, Claude Desktop, or Windsurf):
54
+
55
+ ```json
56
+ {
57
+ "mcpServers": {
58
+ "karjimut": {
59
+ "command": "karjimut",
60
+ "args": ["mcp"]
61
+ }
62
+ }
63
+ }
64
+ ```
65
+
66
+ ### 3. Drop in the Vibecoder Rule
67
+ Copy [`.cursorrules`](.cursorrules) (for Cursor/Windsurf) or [`GEMINI.md`](GEMINI.md) (for Antigravity) into the root of your project workspace.
68
+
69
+ **That's it!** Your AI agent will now autonomously retain memory, recall bug fixes, and synchronize with your team without you ever having to micro-manage it.
70
+
71
+ ---
72
+
73
+ ## 🖥️ Native Desktop Dashboard
74
+
75
+ Prefer a visual control center? Simply open your terminal and type:
76
+
77
+ ```bash
78
+ karjimut
79
+ ```
80
+
81
+ <p align="center">
82
+ <img src="sleep-mcp/assets/karjimut_logo.png" alt="Karjimut Desktop App" width="120" />
83
+ </p>
84
+
85
+ Karjimut includes a modern, high-performance desktop application built with CustomTkinter:
86
+ - **1-Column Smart Onboarding**: Automatically detects your API keys (Google Gemini, Groq, OpenRouter, Claude, OpenAI) or operates in 100% offline rule-based mode.
87
+ - **Elastic Core Editor**: View and fine-tune your project's active identity and mandatory rules, complete with a 1-click rollback mechanism.
88
+ - **Proven Solution Vault**: Search, curate, and review distilled bug resolutions.
89
+ - **Real-Time Sustainability Analytics**: Live tracking of token savings, raw vs. compressed token efficiency, and AI retention metrics.
90
+
91
+ ---
92
+
93
+ ## 🚀 Key Features
94
+
95
+ ### 🧠 Two-Tier Bio-Inspired Memory
96
+ * **Tier 1: Elastic Project Core (Lapis 1)**: Holds your tech stack, core directory layout, and non-negotiable architecture rules. Always compressed, deduplicated, and instant ($O(1)$ overhead at session start).
97
+ * **Tier 2: On-Demand Solution Vault (Lapis 2)**: Zero token cost during normal coding! Solutions to tricky bugs are retrieved on-demand only when a matching error or stack trace occurs.
98
+
99
+ ### 🌙 Autonomous Sleep Cycle (Idle Consolidation)
100
+ During coding sessions, your agent leaves lightweight milestone notes in an asynchronous queue. When you take a coffee break ($\ge 5$ minutes of inactivity), Karjimut's background daemon activates the **Sleep Cycle**—distilling raw logs, updating core rules, and archiving proven solutions into persistent memory.
101
+
102
+ ### 🤝 Multi-Team Git Synchronization
103
+ Karjimut serializes project memory into clean, git-friendly `.karjimut/team_memory.json` files. When you push and pull via Git, your entire team's AI agents automatically inherit everyone's bug fixes and updated rules—completely free of binary database merge conflicts.
104
+
105
+ ### 🔍 High-Precision Hybrid Search
106
+ Combines lexical keyword matching (for exact error codes like `SQLITE_BUSY` or `#nextjs-15`) with 384-dimensional semantic vector embeddings (`BAAI/bge-small-en-v1.5` via CPU-accelerated ONNX + bilingual ID–EN technical synonym expansion & offline feature-hashing fallback) using Reciprocal Rank Fusion (RRF).
107
+
108
+ ### 🤖 100% Autonomous (Zero-Prompt Vibecoder Protocol)
109
+ You don't need to remind your AI agent to use Karjimut. With the workspace rules attached, the agent operates autonomously:
110
+ 1. **At Session Start**: Automatically fetches the latest Project Core and imports any new team memory.
111
+ 2. **During Coding**: Automatically checkpoints progress and technical rules after completing features.
112
+ 3. **When Errors Strike**: Automatically searches the Solution Vault for a one-shot fix before wasting tokens on hallucinated trial-and-error.
113
+
114
+ ---
115
+
116
+ ## 📂 Repository Structure
117
+
118
+ ```text
119
+ Karjimut/
120
+ |-- README.md # Official product documentation & Quick Start
121
+ |-- GEMINI.md # Autonomous Vibecoder Rule (Antigravity IDE)
122
+ |-- .cursorrules # Autonomous Vibecoder Rule (Cursor & Windsurf)
123
+ |-- .agents/rules/sleep-mcp-auto.md # Universal Agent Bootstrap Rule
124
+ |-- sleep-mcp/
125
+ |-- assets/ # Official brand logos, banners, and app icons
126
+ | |-- karjimut_banner.png
127
+ | |-- karjimut_logo.png
128
+ | |-- karjimut.ico
129
+ |-- rules_template/ # Starter templates for new workspaces
130
+ |-- .cursorrules
131
+ |-- antigravity_rules.md
132
+ ```
133
+
134
+ > **Distribution Architecture:**
135
+ > Karjimut is engineered as a high-performance, standalone package. The core engine (MCP server, native GUI, SQLite WAL vector store, and background watcher) is delivered directly via verified binary packages.
136
+
137
+ ---
138
+
139
+ ## 🛡️ Privacy & Local-First Philosophy
140
+
141
+ - **Zero Telemetry**: Karjimut does not track your keystrokes, projects, or personal data.
142
+ - **Local Storage**: All databases, cache, and vector embeddings reside locally on your machine in SQLite WAL mode.
143
+ - **Your Keys, Your Choice**: Use your own API keys, run local Ollama models, or utilize the 100% offline rule-based distiller.
144
+
145
+ ---
146
+
147
+ ## 📄 License
148
+
149
+ Karjimut is open-source software licensed under the **[MIT License](LICENSE)**.
150
+ Copyright © 2026 **Naufal Arhab Fadhil Muhammad**. All rights reserved.
@@ -0,0 +1,172 @@
1
+ Metadata-Version: 2.4
2
+ Name: karjimut
3
+ Version: 2.0.2
4
+ Summary: The Autonomous Long-Term Memory Engine for AI Coding Agents
5
+ Author: Naufal Arhab Fadhil Muhammad
6
+ License-Expression: MIT
7
+ Requires-Python: >=3.10
8
+ Description-Content-Type: text/markdown
9
+ License-File: LICENSE
10
+ Requires-Dist: mcp<2.0.0,>=1.2.0
11
+ Requires-Dist: tiktoken>=0.7.0
12
+ Requires-Dist: python-dotenv>=1.0.0
13
+ Requires-Dist: httpx>=0.27.0
14
+ Requires-Dist: customtkinter>=5.2.0
15
+ Requires-Dist: sqlite-vec>=0.1.6
16
+ Requires-Dist: fastembed>=0.9.0
17
+ Requires-Dist: numpy>=1.21.0
18
+ Provides-Extra: dev
19
+ Requires-Dist: pytest>=8.0.0; extra == "dev"
20
+ Requires-Dist: ruff>=0.4.0; extra == "dev"
21
+ Dynamic: license-file
22
+
23
+ <p align="center">
24
+ <img src="sleep-mcp/assets/karjimut_banner.png" alt="Karjimut Banner" width="720" style="border-radius: 16px;" />
25
+ </p>
26
+
27
+ <h1 align="center">Karjimut</h1>
28
+
29
+ <p align="center">
30
+ <strong>The Autonomous Long-Term Memory Engine for AI Coding Agents</strong><br>
31
+ <em>Stop LLM Amnesia. Cut Token Costs by up to 90%. Keep Cursor, Claude Code, and Antigravity Aligned Forever.</em>
32
+ </p>
33
+
34
+ <p align="center">
35
+ <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
36
+ <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-1.2.0%2B-green.svg" alt="MCP Spec"></a>
37
+ <a href="https://pypi.org/project/karjimut/"><img src="https://img.shields.io/pypi/v/karjimut.svg?color=blue" alt="PyPI Version"></a>
38
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
39
+ <a href="https://github.com/Arapemula/Karjimut"><img src="https://img.shields.io/badge/PRs-Welcome-orange.svg" alt="PRs Welcome"></a>
40
+ </p>
41
+
42
+
43
+ ---
44
+
45
+ ## 💡 The Problem with Modern AI Coding Agents
46
+
47
+ Whether you use **Cursor**, **Claude Code**, **Antigravity IDE**, **Windsurf**, or **Cline**, long-term projects always hit three painful walls:
48
+
49
+ 1. 💸 **Context Window Bloat & Cost Explosions**: As sessions grow, raw conversation logs and messy trial-and-error traces accumulate, burning millions of tokens and draining your API budget.
50
+ 2. 🧠 **Context Rot & Session Amnesia**: Start a fresh session or let compaction trigger, and your agent instantly forgets your core architecture rules, directory structure, and repeats the exact same bugs it spent two hours solving yesterday.
51
+ 3. 🏝️ **Developer Memory Isolation**: Your AI agent's hard-won discoveries on your machine remain trapped locally—your teammates' agents will step on the exact same landmines.
52
+
53
+ **Karjimut** solves all three permanently through a **Two-Tier Bio-Inspired Memory Architecture** powered by the **Model Context Protocol (MCP)** and **Autonomous Idle-Phase Consolidation (Sleep Cycle)**.
54
+
55
+ ---
56
+
57
+ ## ⚡ Quick Start (Ready in 60 Seconds)
58
+
59
+ ### 1. Install Karjimut
60
+ Run this single command in your terminal:
61
+
62
+ ```bash
63
+ # Recommended (Official PyPI package)
64
+ pip install karjimut
65
+ ```
66
+
67
+ *Or install directly from GitHub Releases:*
68
+ ```bash
69
+ pip install https://github.com/Arapemula/Karjimut/releases/download/v2.0.2/karjimut-2.0.2-py3-none-any.whl
70
+ ```
71
+
72
+ *(Or run instantly without installation using [uv](https://github.com/astral-sh/uv): `uvx karjimut`)*
73
+
74
+ ### 2. Connect to Your Favorite AI IDE
75
+ Add Karjimut to your IDE's MCP configuration (`mcp_config.json` in Cursor, Antigravity, Claude Desktop, or Windsurf):
76
+
77
+ ```json
78
+ {
79
+ "mcpServers": {
80
+ "karjimut": {
81
+ "command": "karjimut",
82
+ "args": ["mcp"]
83
+ }
84
+ }
85
+ }
86
+ ```
87
+
88
+ ### 3. Drop in the Vibecoder Rule
89
+ Copy [`.cursorrules`](.cursorrules) (for Cursor/Windsurf) or [`GEMINI.md`](GEMINI.md) (for Antigravity) into the root of your project workspace.
90
+
91
+ **That's it!** Your AI agent will now autonomously retain memory, recall bug fixes, and synchronize with your team without you ever having to micro-manage it.
92
+
93
+ ---
94
+
95
+ ## 🖥️ Native Desktop Dashboard
96
+
97
+ Prefer a visual control center? Simply open your terminal and type:
98
+
99
+ ```bash
100
+ karjimut
101
+ ```
102
+
103
+ <p align="center">
104
+ <img src="sleep-mcp/assets/karjimut_logo.png" alt="Karjimut Desktop App" width="120" />
105
+ </p>
106
+
107
+ Karjimut includes a modern, high-performance desktop application built with CustomTkinter:
108
+ - **1-Column Smart Onboarding**: Automatically detects your API keys (Google Gemini, Groq, OpenRouter, Claude, OpenAI) or operates in 100% offline rule-based mode.
109
+ - **Elastic Core Editor**: View and fine-tune your project's active identity and mandatory rules, complete with a 1-click rollback mechanism.
110
+ - **Proven Solution Vault**: Search, curate, and review distilled bug resolutions.
111
+ - **Real-Time Sustainability Analytics**: Live tracking of token savings, raw vs. compressed token efficiency, and AI retention metrics.
112
+
113
+ ---
114
+
115
+ ## 🚀 Key Features
116
+
117
+ ### 🧠 Two-Tier Bio-Inspired Memory
118
+ * **Tier 1: Elastic Project Core (Lapis 1)**: Holds your tech stack, core directory layout, and non-negotiable architecture rules. Always compressed, deduplicated, and instant ($O(1)$ overhead at session start).
119
+ * **Tier 2: On-Demand Solution Vault (Lapis 2)**: Zero token cost during normal coding! Solutions to tricky bugs are retrieved on-demand only when a matching error or stack trace occurs.
120
+
121
+ ### 🌙 Autonomous Sleep Cycle (Idle Consolidation)
122
+ During coding sessions, your agent leaves lightweight milestone notes in an asynchronous queue. When you take a coffee break ($\ge 5$ minutes of inactivity), Karjimut's background daemon activates the **Sleep Cycle**—distilling raw logs, updating core rules, and archiving proven solutions into persistent memory.
123
+
124
+ ### 🤝 Multi-Team Git Synchronization
125
+ Karjimut serializes project memory into clean, git-friendly `.karjimut/team_memory.json` files. When you push and pull via Git, your entire team's AI agents automatically inherit everyone's bug fixes and updated rules—completely free of binary database merge conflicts.
126
+
127
+ ### 🔍 High-Precision Hybrid Search
128
+ Combines lexical keyword matching (for exact error codes like `SQLITE_BUSY` or `#nextjs-15`) with 384-dimensional semantic vector embeddings (`BAAI/bge-small-en-v1.5` via CPU-accelerated ONNX + bilingual ID–EN technical synonym expansion & offline feature-hashing fallback) using Reciprocal Rank Fusion (RRF).
129
+
130
+ ### 🤖 100% Autonomous (Zero-Prompt Vibecoder Protocol)
131
+ You don't need to remind your AI agent to use Karjimut. With the workspace rules attached, the agent operates autonomously:
132
+ 1. **At Session Start**: Automatically fetches the latest Project Core and imports any new team memory.
133
+ 2. **During Coding**: Automatically checkpoints progress and technical rules after completing features.
134
+ 3. **When Errors Strike**: Automatically searches the Solution Vault for a one-shot fix before wasting tokens on hallucinated trial-and-error.
135
+
136
+ ---
137
+
138
+ ## 📂 Repository Structure
139
+
140
+ ```text
141
+ Karjimut/
142
+ |-- README.md # Official product documentation & Quick Start
143
+ |-- GEMINI.md # Autonomous Vibecoder Rule (Antigravity IDE)
144
+ |-- .cursorrules # Autonomous Vibecoder Rule (Cursor & Windsurf)
145
+ |-- .agents/rules/sleep-mcp-auto.md # Universal Agent Bootstrap Rule
146
+ |-- sleep-mcp/
147
+ |-- assets/ # Official brand logos, banners, and app icons
148
+ | |-- karjimut_banner.png
149
+ | |-- karjimut_logo.png
150
+ | |-- karjimut.ico
151
+ |-- rules_template/ # Starter templates for new workspaces
152
+ |-- .cursorrules
153
+ |-- antigravity_rules.md
154
+ ```
155
+
156
+ > **Distribution Architecture:**
157
+ > Karjimut is engineered as a high-performance, standalone package. The core engine (MCP server, native GUI, SQLite WAL vector store, and background watcher) is delivered directly via verified binary packages.
158
+
159
+ ---
160
+
161
+ ## 🛡️ Privacy & Local-First Philosophy
162
+
163
+ - **Zero Telemetry**: Karjimut does not track your keystrokes, projects, or personal data.
164
+ - **Local Storage**: All databases, cache, and vector embeddings reside locally on your machine in SQLite WAL mode.
165
+ - **Your Keys, Your Choice**: Use your own API keys, run local Ollama models, or utilize the 100% offline rule-based distiller.
166
+
167
+ ---
168
+
169
+ ## 📄 License
170
+
171
+ Karjimut is open-source software licensed under the **[MIT License](LICENSE)**.
172
+ Copyright © 2026 **Naufal Arhab Fadhil Muhammad**. All rights reserved.
@@ -0,0 +1,45 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ karjimut.egg-info/PKG-INFO
5
+ karjimut.egg-info/SOURCES.txt
6
+ karjimut.egg-info/dependency_links.txt
7
+ karjimut.egg-info/entry_points.txt
8
+ karjimut.egg-info/requires.txt
9
+ karjimut.egg-info/top_level.txt
10
+ src/.env.example
11
+ src/__init__.py
12
+ src/archive_manager.py
13
+ src/config.py
14
+ src/consolidator.py
15
+ src/db.py
16
+ src/embedding.py
17
+ src/fts_search.py
18
+ src/idle_watcher.py
19
+ src/ktp_manager.py
20
+ src/llm_distiller.py
21
+ src/log_parser.py
22
+ src/mcp_server.py
23
+ src/run.py
24
+ src/services.py
25
+ src/tokenizer_utils.py
26
+ src/assets/karjimut.ico
27
+ src/assets/karjimut_banner.png
28
+ src/assets/karjimut_logo.png
29
+ src/data/gui_language.json
30
+ src/gui/__init__.py
31
+ src/gui/app_gui.py
32
+ src/gui/i18n.py
33
+ src/gui/key_detector.py
34
+ src/gui/onboarding_dialog.py
35
+ src/gui/project_dialogs.py
36
+ src/gui/shell_layout.py
37
+ src/gui/tab_antrean.py
38
+ src/gui/tab_ktp.py
39
+ src/gui/tab_settings.py
40
+ src/gui/tab_solusi.py
41
+ src/gui/theme.py
42
+ src/rules_template/.cursorrules
43
+ src/rules_template/antigravity_rules.md
44
+ tests/test_unit_core.py
45
+ tests/test_v2_features.py
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ karjimut = karjimut.run:main
3
+ sleep-mcp = karjimut.run:main
@@ -0,0 +1,12 @@
1
+ mcp<2.0.0,>=1.2.0
2
+ tiktoken>=0.7.0
3
+ python-dotenv>=1.0.0
4
+ httpx>=0.27.0
5
+ customtkinter>=5.2.0
6
+ sqlite-vec>=0.1.6
7
+ fastembed>=0.9.0
8
+ numpy>=1.21.0
9
+
10
+ [dev]
11
+ pytest>=8.0.0
12
+ ruff>=0.4.0
@@ -0,0 +1 @@
1
+ karjimut
@@ -0,0 +1,71 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "karjimut"
7
+ version = "2.0.2"
8
+ description = "The Autonomous Long-Term Memory Engine for AI Coding Agents"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ requires-python = ">=3.10"
12
+ authors = [
13
+ { name = "Naufal Arhab Fadhil Muhammad" }
14
+ ]
15
+ dependencies = [
16
+ "mcp>=1.2.0,<2.0.0",
17
+ "tiktoken>=0.7.0",
18
+ "python-dotenv>=1.0.0",
19
+ "httpx>=0.27.0",
20
+ "customtkinter>=5.2.0",
21
+ "sqlite-vec>=0.1.6",
22
+ "fastembed>=0.9.0",
23
+ "numpy>=1.21.0",
24
+ ]
25
+
26
+ [project.optional-dependencies]
27
+ dev = [
28
+ "pytest>=8.0.0",
29
+ "ruff>=0.4.0",
30
+ ]
31
+
32
+ [project.scripts]
33
+ karjimut = "karjimut.run:main"
34
+ sleep-mcp = "karjimut.run:main"
35
+
36
+ [tool.setuptools]
37
+ packages = [
38
+ "karjimut",
39
+ "karjimut.gui",
40
+ "karjimut.assets",
41
+ "karjimut.data",
42
+ "karjimut.rules_template",
43
+ ]
44
+ package-dir = {"karjimut" = "src"}
45
+
46
+ [tool.setuptools.package-data]
47
+ "karjimut" = [
48
+ "assets/*.png",
49
+ "assets/*.ico",
50
+ "data/*.json",
51
+ "rules_template/*.md",
52
+ "rules_template/.cursorrules",
53
+ ".env.example",
54
+ ]
55
+ "karjimut.assets" = ["*.png", "*.ico"]
56
+ "karjimut.data" = ["*.json"]
57
+ "karjimut.rules_template" = ["*.md", ".cursorrules"]
58
+
59
+ [tool.pytest.ini_options]
60
+ testpaths = ["tests"]
61
+ python_files = ["test_*.py"]
62
+ addopts = "-q"
63
+
64
+ [tool.ruff]
65
+ target-version = "py310"
66
+ line-length = 120
67
+ exclude = [".git", ".venv", "venv", "__pycache__", "build", "dist"]
68
+
69
+ [tool.ruff.lint]
70
+ select = ["E", "F", "W", "I"]
71
+ ignore = ["E501"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+