eagle-mem 2.0.2 → 2.0.4

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 (2) hide show
  1. package/README.md +70 -72
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -9,14 +9,16 @@ Persistent memory for [Claude Code](https://docs.anthropic.com/en/docs/claude-co
9
9
 
10
10
  **Zero per-instance overhead.** No daemon, no vector DB, no MCP server. Just bash scripts, sqlite3, and jq.
11
11
 
12
- ## Install
12
+ ## Getting started
13
+
14
+ **1. Install** (once — this is the only setup step):
13
15
 
14
16
  ```bash
15
17
  npm install -g eagle-mem
16
18
  eagle-mem install
17
19
  ```
18
20
 
19
- Start a new Claude Code session — Eagle Mem activates automatically:
21
+ **2. Open Claude Code** in any project directory. Eagle Mem activates automatically:
20
22
 
21
23
  ```
22
24
  █▀▀ ▄▀█ █▀▀ █ █▀▀ █▀▄▀█ █▀▀ █▀▄▀█
@@ -27,44 +29,86 @@ Sessions: 5 recent | Memories: 3 | Tasks: 2 pending
27
29
  Last: Added auth middleware with JWT validation
28
30
  ```
29
31
 
30
- ## What It Does
32
+ **3. That's it.** Everything else is automatic:
33
+ - Session summaries captured on every Claude turn
34
+ - Claude's memories, plans, and tasks mirrored into Eagle Mem
35
+ - Full context re-injected after every `/compact`, `/clear`, or new session
36
+ - Past sessions searched on every prompt via FTS5
37
+
38
+ > **Have existing Claude Code history?** Run `eagle-mem refresh` inside your project directory to backfill — it scans your codebase, indexes source files, and imports all existing memories, plans, and tasks.
39
+
40
+ ## Day-to-day usage
41
+
42
+ Most of the time you don't run anything manually. The hooks handle everything. But when you need to:
43
+
44
+ | When | What to do |
45
+ |------|-----------|
46
+ | Search past sessions | `eagle-mem search "auth middleware"` |
47
+ | See recent timeline | `eagle-mem search --timeline` |
48
+ | View project overview | `eagle-mem overview` |
49
+ | Set a custom overview | `eagle-mem overview set "..."` |
50
+ | Full re-sync after major changes | `eagle-mem refresh .` |
51
+ | Clean up old data | `eagle-mem prune` |
52
+
53
+ Inside Claude Code, you also have skills (slash commands):
54
+
55
+ | Skill | When to use it |
56
+ |-------|---------------|
57
+ | `/eagle-mem-search` | Find something from a past session |
58
+ | `/eagle-mem-overview` | Build a rich project briefing from code + README + git |
59
+ | `/eagle-mem-tasks` | Break complex work into tasks that survive `/compact` |
60
+
61
+ ## Updating
62
+
63
+ ```bash
64
+ npm update -g eagle-mem
65
+ eagle-mem update
66
+ ```
31
67
 
32
- Eagle Mem hooks into Claude Code's lifecycle to solve the context loss problem:
68
+ The `update` command copies new files, runs any pending database migrations, and re-registers hooks. Your data is preserved.
33
69
 
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
70
+ ## How it works
39
71
 
40
- ## Hook Lifecycle
72
+ Five hooks fire automatically at different points in Claude Code's lifecycle:
41
73
 
42
- | Hook | Fires When | What It Does |
74
+ | Hook | Fires when | What it does |
43
75
  |------|-----------|--------------|
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 |
76
+ | **SessionStart** | startup, resume, clear, compact | Injects overview, summaries, memories, tasks |
77
+ | **UserPromptSubmit** | user sends a message | FTS5 search for relevant past context |
78
+ | **PostToolUse** | after tool calls | Records file touches, mirrors memory/plan/task writes |
79
+ | **Stop** | Claude's turn ends | Extracts `<eagle-summary>`, strips `<private>` tags |
48
80
  | **SessionEnd** | session closes | Re-syncs tasks, marks session completed |
49
81
 
50
- ## Commands
82
+ Data lives in a single SQLite database at `~/.eagle-mem/memory.db` (WAL mode, FTS5 full-text search):
83
+
84
+ | Table | What it stores |
85
+ |-------|---------------|
86
+ | sessions | Active/completed sessions per project |
87
+ | summaries | Per-session summaries (FTS5-indexed) |
88
+ | observations | Per-tool-use file touch records |
89
+ | overviews | One overview per project (scan or manual) |
90
+ | code_chunks | FTS5-indexed source file chunks |
91
+ | claude_memories | Mirror of Claude Code auto-memories |
92
+ | claude_plans | Mirror of Claude Code plans |
93
+ | claude_tasks | Mirror of Claude Code tasks |
94
+
95
+ ## All commands
51
96
 
52
97
  | Command | What it does |
53
98
  |---------|-------------|
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
99
  | `eagle-mem install` | First-time setup: hooks, database, skills |
64
100
  | `eagle-mem update` | Re-deploy hooks and run pending migrations |
65
101
  | `eagle-mem uninstall` | Remove hooks and optionally delete data |
102
+ | `eagle-mem refresh` | Full sync: scan + index + memories in one command |
103
+ | `eagle-mem search <query>` | FTS5 search across summaries, memories, and code |
104
+ | `eagle-mem overview` | View or set the project overview |
105
+ | `eagle-mem scan` | Analyze codebase structure |
106
+ | `eagle-mem index` | Index source files for code search |
107
+ | `eagle-mem memories` | View/sync mirrored Claude Code memories and plans |
108
+ | `eagle-mem tasks` | View mirrored Claude Code tasks |
109
+ | `eagle-mem prune` | Remove old observations and orphaned chunks |
66
110
 
67
- ## Skills
111
+ ## All skills
68
112
 
69
113
  Seven skills available inside Claude Code sessions:
70
114
 
@@ -78,52 +122,6 @@ Seven skills available inside Claude Code sessions:
78
122
  | `/eagle-mem-tasks` | TaskAware Compact Loop — break work into tasks that survive compaction |
79
123
  | `/eagle-mem-prune` | Database hygiene — graduated cleanup of stale data |
80
124
 
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
125
  ## Uninstall
128
126
 
129
127
  ```bash
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "eagle-mem",
3
- "version": "2.0.2",
3
+ "version": "2.0.4",
4
4
  "description": "Persistent memory for Claude Code — SQLite + FTS5, no daemon, no bloat",
5
5
  "bin": {
6
6
  "eagle-mem": "bin/eagle-mem"