eagle-mem 2.0.1 → 2.0.3

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 (3) hide show
  1. package/README.md +87 -73
  2. package/lib/hooks.sh +1 -1
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -16,55 +16,115 @@ npm install -g eagle-mem
16
16
  eagle-mem install
17
17
  ```
18
18
 
19
- Start a new Claude Code session — Eagle Mem activates automatically:
19
+ That's it. Eagle Mem registers 5 lifecycle hooks in Claude Code and is fully automatic from here.
20
+
21
+ ## New project
22
+
23
+ Open Claude Code in your project. Eagle Mem activates and shows:
20
24
 
21
25
  ```
22
26
  █▀▀ ▄▀█ █▀▀ █ █▀▀ █▀▄▀█ █▀▀ █▀▄▀█
23
27
  ██▄ █▀█ █▄█ █▄▄ ██▄ █ ▀ █ ██▄ █ ▀ █
24
28
 
25
29
  Project: my-app
26
- Sessions: 5 recent | Memories: 3 | Tasks: 2 pending
27
- Last: Added auth middleware with JWT validation
30
+ Sessions: 0 recent | Memories: 0 | Tasks: 0 pending
28
31
  ```
29
32
 
30
- ## What It Does
33
+ Since no overview exists, Eagle Mem prompts Claude to build one on your first message. After that, every session starts with full context — you don't do anything.
34
+
35
+ **What happens automatically:**
36
+ - Every Claude turn end: session summary saved
37
+ - Every tool use: file touches recorded, Claude's memories/plans/tasks mirrored
38
+ - Every session start (including after `/compact`): overview + summaries + memories + tasks injected
39
+ - Every prompt: FTS5 searches past sessions for relevant context
40
+
41
+ ## Existing project
42
+
43
+ If you've been using Claude Code on a project and want to backfill everything:
44
+
45
+ ```bash
46
+ eagle-mem refresh .
47
+ ```
48
+
49
+ This runs three steps:
50
+ 1. **Scan** — analyzes your codebase structure (languages, frameworks, entry points)
51
+ 2. **Index** — chunks source files into FTS5-searchable pieces
52
+ 3. **Memory sync** — imports all existing Claude Code memories, plans, and tasks
53
+
54
+ Now open Claude Code. Eagle Mem injects your full history from the start.
55
+
56
+ ## Day-to-day usage
31
57
 
32
- Eagle Mem hooks into Claude Code's lifecycle to solve the context loss problem:
58
+ Most of the time you don't run anything manually. The hooks handle everything. But when you need to:
33
59
 
34
- - **Session summaries** — automatically captured when Claude's turn ends, stored in SQLite with FTS5 search
35
- - **Memory mirror** — mirrors Claude Code's auto-memories, plans, and tasks into a searchable database
36
- - **Context injection** — at session start, injects project overview + recent summaries + relevant memories + in-progress tasks
37
- - **Compact survival** — after `/compact`, Eagle Mem re-injects full context so Claude picks up where it left off
38
- - **Privacy** — wrap sensitive content in `<private>` tags and it's stripped before storage
60
+ | When | What to do |
61
+ |------|-----------|
62
+ | Search past sessions | `eagle-mem search "auth middleware"` |
63
+ | See recent timeline | `eagle-mem search --timeline` |
64
+ | View project overview | `eagle-mem overview` |
65
+ | Set a custom overview | `eagle-mem overview set "..."` |
66
+ | Full re-sync after major changes | `eagle-mem refresh .` |
67
+ | Clean up old data | `eagle-mem prune` |
39
68
 
40
- ## Hook Lifecycle
69
+ Inside Claude Code, you also have skills (slash commands):
41
70
 
42
- | Hook | Fires When | What It Does |
71
+ | Skill | When to use it |
72
+ |-------|---------------|
73
+ | `/eagle-mem-search` | Find something from a past session |
74
+ | `/eagle-mem-overview` | Build a rich project briefing from code + README + git |
75
+ | `/eagle-mem-tasks` | Break complex work into tasks that survive `/compact` |
76
+
77
+ ## Updating
78
+
79
+ ```bash
80
+ npm update -g eagle-mem
81
+ eagle-mem update
82
+ ```
83
+
84
+ The `update` command copies new files, runs any pending database migrations, and re-registers hooks. Your data is preserved.
85
+
86
+ ## How it works
87
+
88
+ Five hooks fire automatically at different points in Claude Code's lifecycle:
89
+
90
+ | Hook | Fires when | What it does |
43
91
  |------|-----------|--------------|
44
- | **SessionStart** | startup, resume, clear, compact | Injects project overview, recent summaries, memories, and in-progress tasks |
45
- | **UserPromptSubmit** | user sends a message | Searches FTS5 for memories relevant to the prompt |
46
- | **Stop** | Claude's turn ends | Parses `<eagle-summary>` from transcript, saves to DB |
47
- | **PostToolUse** | after tool calls | Captures observations, mirrors memory/plan/task writes |
92
+ | **SessionStart** | startup, resume, clear, compact | Injects overview, summaries, memories, tasks |
93
+ | **UserPromptSubmit** | user sends a message | FTS5 search for relevant past context |
94
+ | **PostToolUse** | after tool calls | Records file touches, mirrors memory/plan/task writes |
95
+ | **Stop** | Claude's turn ends | Extracts `<eagle-summary>`, strips `<private>` tags |
48
96
  | **SessionEnd** | session closes | Re-syncs tasks, marks session completed |
49
97
 
50
- ## Commands
98
+ Data lives in a single SQLite database at `~/.eagle-mem/memory.db` (WAL mode, FTS5 full-text search):
99
+
100
+ | Table | What it stores |
101
+ |-------|---------------|
102
+ | sessions | Active/completed sessions per project |
103
+ | summaries | Per-session summaries (FTS5-indexed) |
104
+ | observations | Per-tool-use file touch records |
105
+ | overviews | One overview per project (scan or manual) |
106
+ | code_chunks | FTS5-indexed source file chunks |
107
+ | claude_memories | Mirror of Claude Code auto-memories |
108
+ | claude_plans | Mirror of Claude Code plans |
109
+ | claude_tasks | Mirror of Claude Code tasks |
110
+
111
+ ## All commands
51
112
 
52
113
  | Command | What it does |
53
114
  |---------|-------------|
54
- | `eagle-mem refresh` | Full project sync: scan + index + memories sync in one command |
55
- | `eagle-mem search <query>` | FTS5 search across summaries, memories, and code chunks |
56
- | `eagle-mem search --timeline` | Recent sessions in chronological order |
57
- | `eagle-mem overview` | View or set the project overview |
58
- | `eagle-mem scan` | Analyze codebase structure (languages, frameworks, entry points) |
59
- | `eagle-mem index` | Index source files into FTS5-searchable chunks |
60
- | `eagle-mem memories` | View/sync mirrored Claude Code memories, plans, and tasks |
61
- | `eagle-mem tasks` | View mirrored Claude Code tasks |
62
- | `eagle-mem prune` | Remove old observations and orphaned chunks |
63
115
  | `eagle-mem install` | First-time setup: hooks, database, skills |
64
116
  | `eagle-mem update` | Re-deploy hooks and run pending migrations |
65
117
  | `eagle-mem uninstall` | Remove hooks and optionally delete data |
118
+ | `eagle-mem refresh` | Full sync: scan + index + memories in one command |
119
+ | `eagle-mem search <query>` | FTS5 search across summaries, memories, and code |
120
+ | `eagle-mem overview` | View or set the project overview |
121
+ | `eagle-mem scan` | Analyze codebase structure |
122
+ | `eagle-mem index` | Index source files for code search |
123
+ | `eagle-mem memories` | View/sync mirrored Claude Code memories and plans |
124
+ | `eagle-mem tasks` | View mirrored Claude Code tasks |
125
+ | `eagle-mem prune` | Remove old observations and orphaned chunks |
66
126
 
67
- ## Skills
127
+ ## All skills
68
128
 
69
129
  Seven skills available inside Claude Code sessions:
70
130
 
@@ -78,52 +138,6 @@ Seven skills available inside Claude Code sessions:
78
138
  | `/eagle-mem-tasks` | TaskAware Compact Loop — break work into tasks that survive compaction |
79
139
  | `/eagle-mem-prune` | Database hygiene — graduated cleanup of stale data |
80
140
 
81
- ## Database
82
-
83
- Single shared SQLite database at `~/.eagle-mem/memory.db`. WAL mode for concurrent sessions, FTS5 for full-text search.
84
-
85
- | Table | Purpose |
86
- |-------|---------|
87
- | sessions | Active/completed sessions per project |
88
- | summaries | Per-session summaries with FTS5 (UPSERT on session_id) |
89
- | observations | Per-tool-use records with deduplication |
90
- | overviews | One rolling overview per project (scan vs manual source tracking) |
91
- | code_chunks | FTS5-indexed source file chunks |
92
- | claude_memories | Mirror of Claude Code auto-memories |
93
- | claude_plans | Mirror of Claude Code plans |
94
- | claude_tasks | Mirror of Claude Code tasks |
95
-
96
- ## Architecture
97
-
98
- ```
99
- Package (npm) Runtime (~/.eagle-mem/)
100
- ├── bin/eagle-mem CLI ├── memory.db SQLite + FTS5
101
- ├── scripts/ ├── eagle-mem.log Debug log
102
- │ ├── install.sh ├── hooks/
103
- │ ├── update.sh │ ├── session-start.sh
104
- │ ├── uninstall.sh │ ├── user-prompt-submit.sh
105
- │ ├── search.sh │ ├── stop.sh
106
- │ ├── overview.sh │ ├── post-tool-use.sh
107
- │ ├── tasks.sh │ └── session-end.sh
108
- │ ├── prune.sh ├── lib/
109
- │ ├── scan.sh │ ├── common.sh
110
- │ ├── index.sh │ ├── db.sh
111
- │ ├── memories.sh │ └── hooks.sh
112
- │ ├── refresh.sh └── db/
113
- │ └── help.sh ├── schema.sql
114
- ├── hooks/ Source └── [0-9]*.sql Migrations
115
- ├── lib/ Source
116
- ├── db/ Source
117
- └── skills/ → ~/.claude/skills/
118
- ├── eagle-mem-search/
119
- ├── eagle-mem-overview/
120
- ├── eagle-mem-scan/
121
- ├── eagle-mem-index/
122
- ├── eagle-mem-memories/
123
- ├── eagle-mem-tasks/
124
- └── eagle-mem-prune/
125
- ```
126
-
127
141
  ## Uninstall
128
142
 
129
143
  ```bash
package/lib/hooks.sh CHANGED
@@ -13,7 +13,7 @@ eagle_patch_hook() {
13
13
 
14
14
  if jq -e ".hooks.${event}[]? | select(.hooks[]?.command == \"$command\")" "$settings" &>/dev/null; then
15
15
  [ -n "$description" ] && eagle_ok "$description ${DIM}(already registered)${RESET}"
16
- return
16
+ return 0
17
17
  fi
18
18
 
19
19
  local entry
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "eagle-mem",
3
- "version": "2.0.1",
3
+ "version": "2.0.3",
4
4
  "description": "Persistent memory for Claude Code — SQLite + FTS5, no daemon, no bloat",
5
5
  "bin": {
6
6
  "eagle-mem": "bin/eagle-mem"