@purpleraven/hits 0.2.1 → 0.2.2
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.
- package/README.md +260 -223
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,116 +1,91 @@
|
|
|
1
|
-
#
|
|
1
|
+
# hits
|
|
2
2
|
|
|
3
3
|
> Replicate your predecessor's brain as perfectly as possible, using the least amount of AI.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
A secure web-based knowledge management system that preserves organizational context across AI tool sessions. When your Claude session hits the token limit and you switch to a new one — HITS ensures nothing is lost.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## What Problem Does This Solve?
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
You're working on a project with Claude Code. After a long session, you hit the token limit. A new session starts — but it has **no idea** what you did, what decisions were made, or what was left unfinished.
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
- **Context Preservation**: Store decision-making processes in a Why-How-What hierarchy
|
|
13
|
-
- **Failure Experience**: Record failed approaches alongside successes as Negative Paths
|
|
14
|
-
- **Security Hardened**: Argon2id hashing, JWT HttpOnly cookies, CSP, Rate Limiting
|
|
15
|
-
- **AI Session Handover**: Automatically transfer project context when AI sessions rotate due to token limits
|
|
16
|
-
- **Centralized Storage**: All AI tool work logs are consolidated at `~/.hits/data/`
|
|
17
|
-
- **Project Isolation**: Completely independent context management based on project path
|
|
11
|
+
**HITS fixes this:**
|
|
18
12
|
|
|
19
|
-
|
|
13
|
+
1. **Record work** during each AI session (manually or via MCP tools)
|
|
14
|
+
2. **Query handover** when a new session starts — it gets the full context
|
|
15
|
+
3. **Knowledge trees** preserve the WHY/HOW/WHAT of every project
|
|
16
|
+
4. **All AI tools share the same data** — Claude, OpenCode, Cursor, it doesn't matter
|
|
20
17
|
|
|
21
|
-
| Area | Technology |
|
|
22
|
-
|------|-----------|
|
|
23
|
-
| **Backend** | Python 3.10+, FastAPI, Pydantic v2 |
|
|
24
|
-
| **Frontend** | Svelte 5, Vite, TypeScript |
|
|
25
|
-
| **Authentication** | Argon2id (passwords), JWT HS256 (HttpOnly cookies) |
|
|
26
|
-
| **Storage** | File-based (`~/.hits/data/`), Redis (optional) |
|
|
27
|
-
| **Security** | CSP, CORS, Rate Limiting, Secure Headers |
|
|
28
|
-
|
|
29
|
-
## Installation
|
|
30
|
-
|
|
31
|
-
### Requirements
|
|
32
|
-
|
|
33
|
-
- Python 3.10 or later
|
|
34
|
-
- Node.js 18+ (for frontend build)
|
|
35
|
-
- Redis (optional — falls back to file storage)
|
|
36
|
-
|
|
37
|
-
### Quick Start
|
|
38
|
-
|
|
39
|
-
```bash
|
|
40
|
-
cd hits
|
|
41
|
-
./run.sh # Auto-install + start server
|
|
42
18
|
```
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
19
|
+
[OpenCode session ends] [Claude session starts]
|
|
20
|
+
│ │
|
|
21
|
+
Record work: Query handover:
|
|
22
|
+
"Added JWT auth, → Previous: Added JWT auth
|
|
23
|
+
chose Argon2id over → Decisions: Argon2id > bcrypt
|
|
24
|
+
bcrypt, still need to → Pending: rate limiting
|
|
25
|
+
add rate limiting" → Files: auth/manager.py, ...
|
|
48
26
|
```
|
|
49
27
|
|
|
50
|
-
|
|
28
|
+
## Quick Start
|
|
51
29
|
|
|
52
|
-
|
|
53
|
-
# Python environment
|
|
54
|
-
python3 -m venv venv
|
|
55
|
-
source venv/bin/activate
|
|
56
|
-
pip install -r requirements.txt
|
|
30
|
+
### One Command — That's It
|
|
57
31
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
npm install
|
|
61
|
-
npm run build
|
|
62
|
-
cd ..
|
|
63
|
-
|
|
64
|
-
# Start server
|
|
65
|
-
python -m hits_core.main --port 8765
|
|
32
|
+
```bash
|
|
33
|
+
npx hits
|
|
66
34
|
```
|
|
67
35
|
|
|
68
|
-
|
|
36
|
+
That single command will:
|
|
69
37
|
|
|
70
|
-
|
|
38
|
+
1. **Detect Python 3.10+** on your system
|
|
39
|
+
2. **Create a virtual environment** automatically
|
|
40
|
+
3. **Install Python dependencies** (FastAPI, Argon2id, etc.)
|
|
41
|
+
4. **Start the Python backend** (FastAPI on port 8765)
|
|
42
|
+
5. **Start the web server** (Express on port 8765)
|
|
43
|
+
6. Open **http://127.0.0.1:8765** in your browser
|
|
71
44
|
|
|
72
|
-
|
|
73
|
-
|---------|---------------|
|
|
74
|
-
| **Password Hashing** | Argon2id (memory=64MB, iterations=3, parallelism=1) |
|
|
75
|
-
| **Minimum Password Length** | 8 characters |
|
|
76
|
-
| **JWT Tokens** | HttpOnly + Secure + SameSite=Lax cookies |
|
|
77
|
-
| **Access Token** | 15-minute expiry |
|
|
78
|
-
| **Refresh Token** | 7-day expiry, sent only to `/api/auth/refresh` |
|
|
79
|
-
| **First User** | Automatically assigned admin role |
|
|
80
|
-
| **Subsequent Users** | Can only be created by admin |
|
|
45
|
+
### First Time Setup
|
|
81
46
|
|
|
82
|
-
|
|
47
|
+
On first visit, you'll create an admin account:
|
|
83
48
|
|
|
84
49
|
```
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
50
|
+
┌──────────────────────────────────────┐
|
|
51
|
+
│ 🌳 HITS │
|
|
52
|
+
│ Hybrid Intel Trace System │
|
|
53
|
+
│ │
|
|
54
|
+
│ ┌────────────────────────────────┐ │
|
|
55
|
+
│ │ Username: [____________] │ │
|
|
56
|
+
│ │ Password: [____________] │ │
|
|
57
|
+
│ │ │ │
|
|
58
|
+
│ │ [ Create Account ] │ │
|
|
59
|
+
│ │ │ │
|
|
60
|
+
│ │ First account = admin role │ │
|
|
61
|
+
│ └────────────────────────────────┘ │
|
|
62
|
+
└──────────────────────────────────────┘
|
|
91
63
|
```
|
|
92
64
|
|
|
93
|
-
###
|
|
65
|
+
### Custom Port
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
npx hits --port 9000
|
|
69
|
+
# or
|
|
70
|
+
HITS_PORT=9000 npx hits
|
|
71
|
+
```
|
|
94
72
|
|
|
95
|
-
|
|
96
|
-
- Responds with 429 Too Many Requests when exceeded
|
|
73
|
+
## Requirements
|
|
97
74
|
|
|
98
|
-
|
|
75
|
+
| Requirement | Version | Why |
|
|
76
|
+
|-------------|---------|-----|
|
|
77
|
+
| **Node.js** | ≥ 18 | Runs the web server and manages the Python process |
|
|
78
|
+
| **Python** | ≥ 3.10 | Runs the FastAPI backend (auto-installed into venv) |
|
|
99
79
|
|
|
100
|
-
|
|
101
|
-
|------|-------------|-------------|
|
|
102
|
-
| `~/.hits/.auth/users.json` | 600 | User data (owner only) |
|
|
103
|
-
| `~/.hits/.pepper` | 600 | HMAC pepper (owner only) |
|
|
104
|
-
| `~/.hits/.jwt_secret` | 600 | JWT signing key (owner only) |
|
|
105
|
-
| `~/.hits/.auth/` | 700 | Auth directory (owner only) |
|
|
80
|
+
That's it. No database required — HITS uses file-based storage at `~/.hits/data/`.
|
|
106
81
|
|
|
107
|
-
##
|
|
82
|
+
## What You Get
|
|
108
83
|
|
|
109
|
-
###
|
|
84
|
+
### Web UI
|
|
110
85
|
|
|
111
86
|
```
|
|
112
87
|
┌─────────────┬───────────────────────────────────┐
|
|
113
|
-
│ Sidebar │ Header (tabs + user menu)
|
|
88
|
+
│ Sidebar │ Header (tabs + user menu 🌐 lang) │
|
|
114
89
|
│ ├───────────────────────────────────┤
|
|
115
90
|
│ 📂 Projects│ │
|
|
116
91
|
│ ────────── │ Main content area │
|
|
@@ -121,64 +96,181 @@ Permissions-Policy: camera=(), microphone=(), geolocation=()
|
|
|
121
96
|
└─────────────┴───────────────────────────────────┘
|
|
122
97
|
```
|
|
123
98
|
|
|
124
|
-
|
|
99
|
+
**Knowledge Tree** — Organize project knowledge as Why-How-What nodes:
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
📁 Authentication
|
|
103
|
+
├── WHY "Need secure user auth for web UI"
|
|
104
|
+
├── HOW "Argon2id hashing + JWT HttpOnly cookies"
|
|
105
|
+
└── WHAT "POST /api/auth/login → Set-Cookie"
|
|
106
|
+
└── ❌ Negative Path: "Tried bcrypt first — too fast, GPU-vulnerable"
|
|
107
|
+
```
|
|
125
108
|
|
|
126
|
-
|
|
127
|
-
- **Timeline**: Project work logs, grouped by date, with search
|
|
128
|
-
- **Handover**: Auto-generated handover summary when a project is selected
|
|
129
|
-
- **Project Switching**: Instant context switch via sidebar
|
|
130
|
-
- **User Management**: Password change, logout
|
|
109
|
+
**Timeline** — Chronological work log, grouped by date, filterable by project
|
|
131
110
|
|
|
132
|
-
|
|
111
|
+
**Handover** — Auto-generated summary of a project's context, ready to paste into a new AI session
|
|
133
112
|
|
|
134
|
-
|
|
113
|
+
**i18n** — Korean/English toggle (🌐 button in header)
|
|
135
114
|
|
|
136
|
-
|
|
137
|
-
[OpenCode Session] [Claude Session]
|
|
138
|
-
│ │
|
|
139
|
-
Perform work Session start
|
|
140
|
-
│ │
|
|
141
|
-
Record work ──────────────────────→ Query handover
|
|
142
|
-
POST /api/work-log GET /api/handover
|
|
143
|
-
project_path: /my-project project_path: /my-project
|
|
144
|
-
│ │
|
|
145
|
-
└──→ ~/.hits/data/ ←──┘ │
|
|
146
|
-
(centralized) Understand previous context
|
|
147
|
-
│
|
|
148
|
-
Continue work seamlessly
|
|
149
|
-
```
|
|
115
|
+
### MCP Tools for AI Assistants
|
|
150
116
|
|
|
151
|
-
|
|
117
|
+
HITS includes an MCP server so your AI can read and write handover data directly:
|
|
152
118
|
|
|
153
|
-
|
|
119
|
+
#### Register with OpenCode (`~/.config/opencode/opencode.json`)
|
|
154
120
|
|
|
155
121
|
```json
|
|
156
122
|
{
|
|
157
|
-
"
|
|
158
|
-
"
|
|
159
|
-
|
|
160
|
-
|
|
123
|
+
"mcp": {
|
|
124
|
+
"hits": {
|
|
125
|
+
"type": "local",
|
|
126
|
+
"command": ["python", "-m", "hits_core.mcp.server"],
|
|
127
|
+
"cwd": "/path/to/hits"
|
|
128
|
+
}
|
|
161
129
|
}
|
|
162
130
|
}
|
|
163
131
|
```
|
|
164
132
|
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
-
|
|
170
|
-
|
|
133
|
+
#### Register with Claude Code
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
claude mcp add hits \
|
|
137
|
+
-e HITS_DATA_PATH="$HOME/.hits/data" \
|
|
138
|
+
-- python -m hits_core.mcp.server
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
#### 5 MCP Tools
|
|
142
|
+
|
|
143
|
+
| Tool | What It Does |
|
|
144
|
+
|------|-------------|
|
|
145
|
+
| `hits_record_work` | Record a work entry (auto-detects project path from CWD) |
|
|
146
|
+
| `hits_get_handover` | Get handover summary for the current project |
|
|
147
|
+
| `hits_search_works` | Search past work by keyword |
|
|
148
|
+
| `hits_list_projects` | List all projects with recorded work |
|
|
149
|
+
| `hits_get_recent` | Get the most recent work entries |
|
|
150
|
+
|
|
151
|
+
#### Example AI Workflow
|
|
152
|
+
|
|
153
|
+
```
|
|
154
|
+
User: "Continue working on the auth system"
|
|
155
|
+
|
|
156
|
+
AI (auto-calls hits_get_handover):
|
|
157
|
+
→ Previous session added Argon2id password hashing
|
|
158
|
+
→ Decisions: Argon2id (not bcrypt), JWT HS256, HttpOnly cookies
|
|
159
|
+
→ Pending: Rate limiting, password change endpoint
|
|
160
|
+
|
|
161
|
+
AI: "I see the auth system uses Argon2id + JWT. Let me add rate limiting..."
|
|
162
|
+
|
|
163
|
+
(later)
|
|
164
|
+
|
|
165
|
+
AI (auto-calls hits_record_work):
|
|
166
|
+
→ Recorded: "Added rate limiting (10 req/min on login endpoint)"
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### REST API
|
|
170
|
+
|
|
171
|
+
All features are also accessible via HTTP API:
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
# Health check
|
|
175
|
+
curl http://localhost:8765/api/health
|
|
176
|
+
|
|
177
|
+
# Record work
|
|
178
|
+
curl -X POST http://localhost:8765/api/work-log \
|
|
179
|
+
-H "Content-Type: application/json" \
|
|
180
|
+
-b cookies.txt \
|
|
181
|
+
-d '{
|
|
182
|
+
"performed_by": "claude",
|
|
183
|
+
"request_text": "Added rate limiting to login endpoint",
|
|
184
|
+
"context": "10 req/min per IP, 429 response on limit",
|
|
185
|
+
"project_path": "/home/user/my-project",
|
|
186
|
+
"tags": ["security", "api"]
|
|
187
|
+
}'
|
|
188
|
+
|
|
189
|
+
# Get handover summary
|
|
190
|
+
curl "http://localhost:8765/api/handover?project_path=/home/user/my-project" \
|
|
191
|
+
-b cookies.txt
|
|
192
|
+
|
|
193
|
+
# Search past work
|
|
194
|
+
curl "http://localhost:8765/api/work-logs/search?q=auth" \
|
|
195
|
+
-b cookies.txt
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## Security
|
|
199
|
+
|
|
200
|
+
HITS is built with security as a first-class concern:
|
|
201
|
+
|
|
202
|
+
| Feature | Implementation |
|
|
203
|
+
|---------|---------------|
|
|
204
|
+
| **Password Hashing** | Argon2id (64MB memory, 3 iterations, parallelism=1) |
|
|
205
|
+
| **JWT Tokens** | HttpOnly + Secure + SameSite=Lax cookies |
|
|
206
|
+
| **Access Token** | 15-minute expiry |
|
|
207
|
+
| **Refresh Token** | 7-day expiry, restricted to `/api/auth/refresh` path |
|
|
208
|
+
| **Brute Force Protection** | 10 login attempts/minute per IP |
|
|
209
|
+
| **Security Headers** | CSP, X-Frame-Options: DENY, HSTS preload, nosniff |
|
|
210
|
+
| **Data Protection** | Auth files stored with `chmod 600` (owner-only) |
|
|
211
|
+
| **First User Policy** | First registered user becomes admin; subsequent users need admin approval |
|
|
212
|
+
|
|
213
|
+
## How It Works Under the Hood
|
|
214
|
+
|
|
215
|
+
```
|
|
216
|
+
npx hits
|
|
217
|
+
│
|
|
218
|
+
├── 1. findPython() → Detect Python 3.10+ on system
|
|
219
|
+
├── 2. setupPython() → Create venv, install deps
|
|
220
|
+
├── 3. startBackend() → Spawn FastAPI process (port 8765)
|
|
221
|
+
└── 4. startExpress() → Serve frontend + proxy /api → FastAPI
|
|
222
|
+
|
|
223
|
+
Browser Express (8765) FastAPI (8765 internal)
|
|
224
|
+
│ │ │
|
|
225
|
+
├── GET / ───→ static (Svelte SPA) │
|
|
226
|
+
├── GET /some/route ───→ SPA fallback │
|
|
227
|
+
└── GET /api/* ───→ proxy ──────────────→ FastAPI routes
|
|
228
|
+
POST /api/* ───→ proxy ──────────────→ FastAPI routes
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
All data is stored centrally:
|
|
171
232
|
|
|
172
|
-
|
|
233
|
+
```
|
|
234
|
+
~/.hits/
|
|
235
|
+
├── data/ ← All project data
|
|
236
|
+
│ ├── work_logs/ ← AI session work logs (JSON)
|
|
237
|
+
│ ├── trees/ ← Knowledge trees
|
|
238
|
+
│ └── workflows/ ← Workflows
|
|
239
|
+
├── .auth/ ← User accounts (chmod 700)
|
|
240
|
+
│ └── users.json ← User data (chmod 600)
|
|
241
|
+
├── .pepper ← HMAC pepper (chmod 600)
|
|
242
|
+
└── .jwt_secret ← JWT signing key (chmod 600)
|
|
243
|
+
|
|
244
|
+
Override with HITS_DATA_PATH environment variable
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
## CLI Options
|
|
248
|
+
|
|
249
|
+
```
|
|
250
|
+
npx hits [options]
|
|
251
|
+
|
|
252
|
+
Options:
|
|
253
|
+
-p, --port <port> Server port (default: 8765)
|
|
254
|
+
-d, --dev Development mode (verbose logging)
|
|
255
|
+
-s, --setup Install dependencies only, don't start
|
|
256
|
+
-h, --help Show help
|
|
257
|
+
|
|
258
|
+
Environment:
|
|
259
|
+
HITS_PORT Server port override
|
|
260
|
+
HITS_PYTHON Path to python executable (default: auto-detect)
|
|
261
|
+
HITS_DATA_PATH Data storage path (default: ~/.hits/data)
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
## API Reference
|
|
173
265
|
|
|
174
266
|
### Authentication
|
|
175
267
|
|
|
176
268
|
| Method | Path | Description |
|
|
177
269
|
|--------|------|-------------|
|
|
178
|
-
| GET | `/api/auth/status` | Check auth status |
|
|
179
|
-
| POST | `/api/auth/register` | Register user |
|
|
180
|
-
| POST | `/api/auth/login` | Login
|
|
181
|
-
| POST | `/api/auth/logout` | Logout |
|
|
270
|
+
| GET | `/api/auth/status` | Check if auth is initialized, current login status |
|
|
271
|
+
| POST | `/api/auth/register` | Register user (first user = admin) |
|
|
272
|
+
| POST | `/api/auth/login` | Login — sets HttpOnly cookies |
|
|
273
|
+
| POST | `/api/auth/logout` | Logout — clears cookies |
|
|
182
274
|
| POST | `/api/auth/refresh` | Refresh access token |
|
|
183
275
|
| GET | `/api/auth/me` | Get current user info |
|
|
184
276
|
| PUT | `/api/auth/password` | Change password |
|
|
@@ -188,8 +280,8 @@ MCP Tools:
|
|
|
188
280
|
| Method | Path | Description |
|
|
189
281
|
|--------|------|-------------|
|
|
190
282
|
| POST | `/api/work-log` | Create work log |
|
|
191
|
-
| GET | `/api/work-logs` | List
|
|
192
|
-
| GET | `/api/work-logs/search?q=...` | Search
|
|
283
|
+
| GET | `/api/work-logs` | List logs (filter by `project_path`) |
|
|
284
|
+
| GET | `/api/work-logs/search?q=...` | Search logs by keyword |
|
|
193
285
|
| GET | `/api/work-log/{id}` | Get single entry |
|
|
194
286
|
| PUT | `/api/work-log/{id}` | Update entry |
|
|
195
287
|
| DELETE | `/api/work-log/{id}` | Delete entry |
|
|
@@ -199,10 +291,10 @@ MCP Tools:
|
|
|
199
291
|
| Method | Path | Description |
|
|
200
292
|
|--------|------|-------------|
|
|
201
293
|
| GET | `/api/handover?project_path=...` | Get project handover summary |
|
|
202
|
-
| GET | `/api/handover/projects` | List projects |
|
|
203
|
-
| GET | `/api/handover/project-stats?project_path=...` | Get project
|
|
294
|
+
| GET | `/api/handover/projects` | List all projects |
|
|
295
|
+
| GET | `/api/handover/project-stats?project_path=...` | Get project statistics |
|
|
204
296
|
|
|
205
|
-
### Knowledge
|
|
297
|
+
### Knowledge
|
|
206
298
|
|
|
207
299
|
| Method | Path | Description |
|
|
208
300
|
|--------|------|-------------|
|
|
@@ -210,127 +302,72 @@ MCP Tools:
|
|
|
210
302
|
| POST | `/api/knowledge/category` | Create category |
|
|
211
303
|
| PUT | `/api/knowledge/category/{name}` | Update category |
|
|
212
304
|
| DELETE | `/api/knowledge/category/{name}` | Delete category |
|
|
213
|
-
| POST | `/api/knowledge/category/{name}/nodes` | Add node |
|
|
305
|
+
| POST | `/api/knowledge/category/{name}/nodes` | Add node to category |
|
|
214
306
|
| PUT | `/api/knowledge/category/{name}/nodes/{idx}` | Update node |
|
|
215
307
|
| DELETE | `/api/knowledge/category/{name}/nodes/{idx}` | Delete node |
|
|
216
308
|
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
| AI Tool | Value |
|
|
220
|
-
|---------|-------|
|
|
221
|
-
| OpenCode | `opencode` |
|
|
222
|
-
| Claude Code | `claude` |
|
|
223
|
-
| Cursor | `cursor` |
|
|
224
|
-
| Manual | `manual` |
|
|
225
|
-
|
|
226
|
-
## Architecture
|
|
227
|
-
|
|
228
|
-
```
|
|
229
|
-
┌──────────────────────────────────────────────────────────┐
|
|
230
|
-
│ hits_web (Svelte 5 + Vite) │
|
|
231
|
-
│ Material Dark theme · TypeScript │
|
|
232
|
-
│ ┌──────────┬──────────┬──────────────────────────┐ │
|
|
233
|
-
│ │ Sidebar │ Knowledge│ HandoverPanel │ │
|
|
234
|
-
│ │ Projects │ Tree │ Handover summary view │ │
|
|
235
|
-
│ │ Filter │ Timeline │ │ │
|
|
236
|
-
│ └──────────┴──────────┴──────────────────────────┘ │
|
|
237
|
-
│ ↕ API Client (fetch + HttpOnly cookies) │
|
|
238
|
-
├──────────────────────────────────────────────────────────┤
|
|
239
|
-
│ hits_core (Apache 2.0) │
|
|
240
|
-
│ ┌──────────┬──────────┬──────────┬──────────┐ │
|
|
241
|
-
│ │ Models │ Storage │ AI │ Auth │ │
|
|
242
|
-
│ │ Tree │ Redis │ Compress │ Argon2id │ │
|
|
243
|
-
│ │ Node │ File │ SLM/LLM │ JWT │ │
|
|
244
|
-
│ │ WorkLog │(~/.hits) │ Filter │ Middleware│ │
|
|
245
|
-
│ └──────────┴──────────┴──────────┴──────────┘ │
|
|
246
|
-
│ ┌──────────┬──────────┬──────────┐ │
|
|
247
|
-
│ │ API │ Collector│ MCP │ │
|
|
248
|
-
│ │ FastAPI │ Git/Shell│ Server │ │
|
|
249
|
-
│ │ + Static │ AI Sess. │ 5 Tools │ │
|
|
250
|
-
│ │ Serve │ │ │ │
|
|
251
|
-
│ └──────────┴──────────┴──────────┘ │
|
|
252
|
-
│ ┌──────────────────────────────┐ │
|
|
253
|
-
│ │ Service Layer │ │
|
|
254
|
-
│ │ TreeService HandoverService│ │
|
|
255
|
-
│ │ KnowledgeService │ │
|
|
256
|
-
│ └──────────────────────────────┘ │
|
|
257
|
-
└──────────────────────────────────────────────────────────┘
|
|
258
|
-
```
|
|
259
|
-
|
|
260
|
-
## Knowledge Tree Structure
|
|
261
|
-
|
|
262
|
-
### Why-How-What Hierarchy
|
|
309
|
+
## Troubleshooting
|
|
263
310
|
|
|
264
|
-
|
|
265
|
-
├── WHY (Intent/Purpose)
|
|
266
|
-
│ ├── "Why was this system built?"
|
|
267
|
-
│ └── "What is the business goal?"
|
|
268
|
-
│
|
|
269
|
-
├── HOW (Logic/Method)
|
|
270
|
-
│ ├── "How was it implemented?"
|
|
271
|
-
│ └── "What decisions were made?"
|
|
272
|
-
│
|
|
273
|
-
└── WHAT (Execution/Tasks)
|
|
274
|
-
├── "What specifically does it do?"
|
|
275
|
-
└── "Actionable tasks"
|
|
276
|
-
```
|
|
311
|
+
### "Python 3.10+ not found"
|
|
277
312
|
|
|
278
|
-
|
|
313
|
+
Install Python 3.10 or later:
|
|
314
|
+
```bash
|
|
315
|
+
# Ubuntu/Debian
|
|
316
|
+
sudo apt install python3.12
|
|
279
317
|
|
|
280
|
-
|
|
318
|
+
# macOS
|
|
319
|
+
brew install python@3.12
|
|
281
320
|
|
|
282
|
-
|
|
283
|
-
|
|
321
|
+
# Or set manually:
|
|
322
|
+
export HITS_PYTHON=/usr/bin/python3.12
|
|
284
323
|
```
|
|
285
324
|
|
|
286
|
-
###
|
|
325
|
+
### "Frontend not built"
|
|
287
326
|
|
|
327
|
+
This shouldn't happen with the npm package (frontend is pre-built). If it does:
|
|
288
328
|
```bash
|
|
289
|
-
|
|
329
|
+
npx hits --setup
|
|
290
330
|
```
|
|
291
331
|
|
|
292
|
-
###
|
|
332
|
+
### "ModuleNotFoundError: No module named 'hits_core'"
|
|
293
333
|
|
|
334
|
+
Python dependencies failed to install. Try:
|
|
294
335
|
```bash
|
|
295
|
-
|
|
296
|
-
npm install # Install dependencies
|
|
297
|
-
npm run dev # Vite dev server (http://localhost:5173)
|
|
298
|
-
npm run build # Production build
|
|
336
|
+
npx hits --setup
|
|
299
337
|
```
|
|
300
338
|
|
|
301
|
-
|
|
339
|
+
### Redis Connection Failed
|
|
302
340
|
|
|
303
|
-
|
|
304
|
-
|---------|---------|---------------|
|
|
305
|
-
| `hits_core` | Apache 2.0 | ✅ Free |
|
|
306
|
-
| `hits_web` | Apache 2.0 | ✅ Free |
|
|
341
|
+
Not a problem — HITS automatically uses file-based storage. Redis is optional.
|
|
307
342
|
|
|
308
|
-
##
|
|
343
|
+
## Development
|
|
309
344
|
|
|
310
|
-
|
|
345
|
+
If you're working on HITS itself:
|
|
311
346
|
|
|
312
347
|
```bash
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
sudo apt install -y nodejs
|
|
316
|
-
```
|
|
348
|
+
git clone https://github.com/lhjnano/hits.git
|
|
349
|
+
cd hits
|
|
317
350
|
|
|
318
|
-
|
|
351
|
+
# Backend setup
|
|
352
|
+
python3 -m venv venv
|
|
353
|
+
source venv/bin/activate
|
|
354
|
+
pip install -r requirements.txt
|
|
319
355
|
|
|
320
|
-
|
|
356
|
+
# Frontend build
|
|
357
|
+
cd hits_web && npm install && npm run build && cd ..
|
|
321
358
|
|
|
322
|
-
|
|
359
|
+
# Development mode (Vite HMR + FastAPI)
|
|
360
|
+
./run.sh --dev
|
|
323
361
|
|
|
362
|
+
# Run tests
|
|
363
|
+
./run.sh --test
|
|
324
364
|
```
|
|
325
|
-
~/.hits/
|
|
326
|
-
├── data/ ← Default location for all data
|
|
327
|
-
│ ├── work_logs/ ← AI session work logs
|
|
328
|
-
│ ├── trees/ ← Knowledge trees
|
|
329
|
-
│ └── workflows/ ← Workflows
|
|
330
|
-
├── .auth/ ← Authentication data
|
|
331
|
-
│ └── users.json ← User info (permissions 600)
|
|
332
|
-
├── .pepper ← HMAC pepper (permissions 600)
|
|
333
|
-
└── .jwt_secret ← JWT signing key (permissions 600)
|
|
334
365
|
|
|
335
|
-
|
|
336
|
-
|
|
366
|
+
## License
|
|
367
|
+
|
|
368
|
+
Apache 2.0 — free for commercial use.
|
|
369
|
+
|
|
370
|
+
## Links
|
|
371
|
+
|
|
372
|
+
- **GitHub**: [https://github.com/lhjnano/hits](https://github.com/lhjnano/hits)
|
|
373
|
+
- **Issues**: [https://github.com/lhjnano/hits/issues](https://github.com/lhjnano/hits/issues)
|