@anmol-srv/sigil 0.18.2 → 0.22.0

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. package/README.md +37 -25
  2. package/dist/cli.js +1191 -790
  3. package/dist/daemon.js +664 -302
  4. package/dist/hooks/post-tool-use.js +1 -69
  5. package/dist/hooks/session-end.js +13 -236
  6. package/dist/hooks/stop.js +36 -246
  7. package/dist/hooks/user-prompt-submit.js +25 -288
  8. package/dist/mcp/worker-server.js +6 -0
  9. package/dist/npm-entry.js +10 -0
  10. package/dist/server.js +64 -56
  11. package/install.sh +207 -0
  12. package/integrations/hermes/README.md +30 -24
  13. package/integrations/hermes/plugin/README.md +1 -1
  14. package/integrations/hermes/plugin/__init__.py +68 -24
  15. package/knexfile.js +19 -22
  16. package/package.json +9 -28
  17. package/prompts/audm-decision.md +26 -1
  18. package/prompts/entity-extraction.md +32 -30
  19. package/prompts/graph-extraction.md +20 -2
  20. package/src/db/drivers/index.js +38 -15
  21. package/src/db/migrations/20260629120000_add-trace-event-attribution.cjs +29 -0
  22. package/src/db/migrations/20260629120001_add-llm-log-session-correlation.cjs +29 -0
  23. package/src/db/migrations/20260806120000_add-document-content.cjs +27 -0
  24. package/src/db/migrations/20260806120001_llm-log-model-nullable.cjs +36 -0
  25. package/src/db/migrations/20260811120000_add-relation-provenance.cjs +42 -0
  26. package/src/db/migrations/20260811130000_add-fact-visibility.cjs +67 -0
  27. package/src/db/migrations/20260813090000_rescore-defaulted-vital.cjs +57 -0
  28. package/src/db/migrations/20260814120000_create-ingestion-job.cjs +52 -0
  29. package/src/db/migrations/20260814120100_add-llm-log-queued-ms.cjs +8 -0
  30. package/src/db/migrations/20260814120200_add-active-fact-content-hash-index.cjs +16 -0
  31. package/src/db/migrations/20260814120300_create-relation-candidate-judgment.cjs +25 -0
  32. package/src/gui/web/app.css +851 -84
  33. package/src/gui/web/app.js +796 -383
  34. package/src/gui/web/cmdk.js +238 -0
  35. package/src/gui/web/components.js +64 -0
  36. package/src/gui/web/design/colors_and_type.css +6 -1
  37. package/src/gui/web/graph/GraphIsland.jsx +450 -0
  38. package/src/gui/web/graph/cluster.js +305 -0
  39. package/src/gui/web/graph/cluster.test.js +219 -0
  40. package/src/gui/web/health.js +117 -0
  41. package/src/gui/web/health.test.js +159 -0
  42. package/src/gui/web/icons.js +65 -0
  43. package/src/gui/web/index.html +310 -115
  44. package/src/gui/web/settings.js +386 -0
  45. package/src/gui/web/setup.js +2 -2
  46. package/src/gui/web/toast.js +6 -3
  47. package/src/gui/web/vendor/graph-island.js +52 -0
package/README.md CHANGED
@@ -11,17 +11,28 @@ Local-first memory shared across Claude Code, Codex CLI, Cursor, Kiro, and any a
11
11
  </div>
12
12
 
13
13
  ```bash
14
- npx @anmol-srv/sigil
14
+ npm i -g @anmol-srv/sigil && sigil
15
15
  ```
16
16
 
17
- That's it. The command launches Sigil and opens a dashboard in your browser where you configure everything — database, LLM, and embedding provider — with live connection tests and one-click fixes. No config files to edit, no setup prompts in the terminal.
17
+ ```bash
18
+ curl -fsSL https://raw.githubusercontent.com/Anmol-Srv/sigil/master/install.sh | sh
19
+ ```
20
+
21
+ Both commands install the same latest release into `~/.sigil` and start setup in your browser or terminal. So does `npx @anmol-srv/sigil`. Sigil needs Node.js 20+ and Git.
22
+
23
+ Update any time with:
24
+
25
+ ```bash
26
+ sigil update # or: npm i -g @anmol-srv/sigil@latest
27
+ ```
28
+
29
+ The background daemon checks for updates and tells you when one is ready.
18
30
 
19
31
  <div align="center">
20
32
 
21
33
  Configure in the dashboard. Open Claude Code. Memory is already wired in.
22
34
 
23
- [![npm](https://img.shields.io/npm/v/@anmol-srv%2Fsigil)](https://www.npmjs.com/package/@anmol-srv/sigil)
24
- [![Docs](https://img.shields.io/badge/docs-anmol--srv.github.io%2Fsigil-5e8cff)](https://anmol-srv.github.io/sigil/)
35
+ [![Docs](https://img.shields.io/badge/docs-sigil--web.pages.dev-5e8cff)](https://sigil-web.pages.dev/docs/)
25
36
  [![MCP](https://img.shields.io/badge/MCP-native-8B5CF6)](https://modelcontextprotocol.io/)
26
37
  [![Benchmark](https://img.shields.io/badge/LongMemEval%20oracle-R@10%20100%25-6B1A2A)](./eval/longmemeval/RESULTS.md)
27
38
  [![License](https://img.shields.io/badge/license-MIT-blue)](https://opensource.org/licenses/MIT)
@@ -40,7 +51,7 @@ And every agent has its own walled memory. Claude doesn't see what you told Code
40
51
 
41
52
  Sigil fixes both problems with the same primitive: a local memory layer every agent connects to.
42
53
 
43
- - **In Claude Code:** four hooks (`UserPromptSubmit`, `PostToolUse`, `Stop`, `SessionEnd`) auto-capture decisions, preferences, and observations as you work. Relevant memory is injected into every new prompt before Claude sees it. You write zero `sigil remember` calls.
54
+ - **In Claude Code:** hooks warm up memory at session start, look up relevant context for each prompt, capture durable facts after turns, and finalize the session.
44
55
  - **Everywhere else, the `sigil` CLI is the universal interface.** Any agent that can run a shell command (Codex CLI, terminal-based assistants, CI runners, Hermes, your own scripts) can call `sigil search "..."` or `sigil remember "..."` directly. No client integration required: if the agent can shell out, it can read and write memory.
45
56
  - **For MCP-aware clients** (Cursor, Continue, Cline, Windsurf, Claude Desktop, Kiro): the same memory is also exposed as a 9-tool MCP server. Same brain, structured surface for clients that prefer it.
46
57
  - **Across machines:** point multiple installs at the same Postgres. A fact captured on your laptop surfaces in the agent running on your home server. No daemon, no sync protocol. Postgres handles consistency.
@@ -57,7 +68,7 @@ Sigil's wedge is one memory layer underneath everything. `sigil init` detects ev
57
68
 
58
69
  | Agent | Integration depth | Auto-wired |
59
70
  |---|---|---|
60
- | **Claude Code** | Native plugin · 4 hooks (`UserPromptSubmit`, `PostToolUse`, `Stop`, `SessionEnd`) · MCP server · `@~/.sigil/CLAUDE.md` hot-context import | ✓ |
71
+ | **Claude Code** | Four hooks (`SessionStart`, `UserPromptSubmit`, `Stop`, `SessionEnd`) · MCP server · `@~/.sigil/CLAUDE.md` context import | ✓ |
61
72
  | **Codex CLI** | `~/.codex/config.toml` MCP entry · `~/.codex/AGENTS.md` steering · MCP server | ✓ |
62
73
  | **Cursor** | `~/.cursor/mcp.json` MCP entry · MCP server | ✓ |
63
74
  | **Kiro** | `~/.kiro/settings/mcp.json` MCP entry · `~/.kiro/steering/sigil.md` steering rule · MCP server | ✓ |
@@ -78,7 +89,7 @@ sigil facts --limit=20 # list recent facts
78
89
  sigil why "auth setup" # explain the search
79
90
  ```
80
91
 
81
- That's exactly how Claude Code (via Bash tool), Codex CLI, terminal-based agents, Hermes, and your own CI scripts use Sigil today. The CLI is auto-detected on `PATH` after `npm install -g @anmol-srv/sigil`; agents discover it the same way they discover `git` or `node`.
92
+ That's exactly how Claude Code (via Bash tool), Codex CLI, terminal-based agents, Hermes, and your own CI scripts use Sigil today. The CLI is auto-detected on `PATH` once installed (via the `curl … | sh` installer); agents discover it the same way they discover `git` or `node`.
82
93
 
83
94
  For clients that prefer structured tool calls (Cursor, Continue, Cline, Claude Desktop, Kiro, any MCP-spec agent), Sigil also exposes the same memory as a 9-tool MCP server. `sigil register --print` generates the config. MCP is the second interface, not the only one.
84
95
 
@@ -128,7 +139,7 @@ Retrieval is hybrid: pgvector cosine + tsvector keyword fused via Reciprocal Ran
128
139
  | Hook | What runs |
129
140
  |---|---|
130
141
  | `UserPromptSubmit` | Hybrid search on your prompt → top-K facts injected as `additionalContext` before Claude sees it |
131
- | `PostToolUse` | Capture observations from `Edit` / `Write` / `Bash`; SHA-256 dedup against a 5-minute window |
142
+ | `SessionStart` | Warm up the memory service and provide a short readiness and context preamble |
132
143
  | `Stop` | Classify the user's last message (preference / decision / constraint / claim), extract atomic facts + entities, AUDM (Add / Update / Delete / Merge) against existing memory to prevent duplicates |
133
144
  | `SessionEnd` | Summarize the session into its `claude_session` pod; promote sticky facts to higher importance |
134
145
 
@@ -145,7 +156,7 @@ Retrieval is hybrid: pgvector cosine + tsvector keyword fused via Reciprocal Ran
145
156
  | **Pluggable pods** | Five built-in kinds; add `slack_channel`, `github_pr`, `codex_session`, etc. as contract files. No schema migrations |
146
157
  | **AUDM dedup** | Add / Update / Delete / Merge intelligence stops fact pile-up across thousands of saves |
147
158
  | **Fully air-gappable** | Pick Ollama for both LLM and embeddings. Zero data leaves your network |
148
- | **No vendor account** | `npm install` + your Postgres = working brain. No signup, no API key required to start |
159
+ | **No vendor account** | One `curl … | sh` install + your Postgres = working brain. No signup, no API key required to start |
149
160
  | **Hot-context snapshot** | Top-20 facts always loaded via `@~/.sigil/CLAUDE.md` import. Instant context with zero latency |
150
161
  | **9-tool MCP server** | `search`, `search_entity`, `traverse_graph`, `get_fact_context`, `get_entity_context`, `get_pod`, `list_pods`, `status`, `ingest` |
151
162
  | **Honest benchmarks** | Public LongMemEval oracle: R@10 = 100%, 33ms p50 search. Reproducible. No in-house corpus theater |
@@ -154,23 +165,25 @@ Retrieval is hybrid: pgvector cosine + tsvector keyword fused via Reciprocal Ran
154
165
 
155
166
  ## Quickstart
156
167
 
157
- Sigil needs **Postgres 13+ with the `pgvector` extension** running somewhere reachable. You bring the server; the dashboard does everything else.
168
+ Choose the **built-in database** to get started without installing Postgres or Docker. You'll also need an LLM and an embedding provider. The setup wizard can use supported providers you already have.
158
169
 
159
- ### 1. Launch
170
+ ### 1. Install & launch
160
171
 
161
172
  ```bash
162
- npx @anmol-srv/sigil
173
+ npm i -g @anmol-srv/sigil && sigil
174
+ # or
175
+ curl -fsSL https://raw.githubusercontent.com/Anmol-Srv/sigil/master/install.sh | sh
163
176
  ```
164
177
 
165
- This starts the Sigil daemon and opens the dashboard in your browser. The daemon runs even before anything is configured, so the setup wizard is always reachable. Everything below happens in the UI — no terminal prompts, no editing `~/.sigil/.env` by hand.
178
+ Either way, Sigil installs into `~/.sigil`. On a desktop, this opens the setup wizard in your browser. On a headless machine with an interactive terminal, setup runs in the terminal. If you install from CI or a shell without a terminal, open a new shell and run `sigil init` when you're ready.
166
179
 
167
180
  ### 2. Configure in the dashboard
168
181
 
169
- The first-run wizard walks you through three things, each with a live test before it's saved:
182
+ The wizard walks you through storage and providers with live checks:
170
183
 
171
- 1. **Database** — paste a connection URL (Neon, Supabase, AWS RDS, Render, Railway, CockroachDB, …) or point at a local Postgres. The dashboard tests the connection, offers one-click **Install pgvector** if the extension is missing, and runs migrations. Pooled connection URLs (e.g. Neon's `-pooler` host) are handled automatically — migrations run against the direct endpoint.
184
+ 1. **Database** — use the built-in database, connect to local Postgres, use Docker, or provide a connection URL for an external Postgres instance. The wizard can set up the database schema and enable pgvector when the database role has permission.
172
185
  2. **LLM provider** — OpenRouter, OpenAI, Anthropic, Ollama, or your Claude Code subscription. Tested with a live call.
173
- 3. **Embedding provider** — OpenAI, Voyage, or Ollama. If your database already holds vectors at a different dimension than the provider produces, the dashboard tells you exactly how many rows are affected and lets you wipe and start fresh or cancel — never a silent failure.
186
+ 3. **Embedding provider** — OpenAI, Voyage, OpenRouter, or Ollama. Setup tests a compatible 1024-dimensional embedding before saving the provider.
174
187
 
175
188
  When a step fails, the dashboard shows the real cause and the fix, not a generic error. Switch any provider later from **Settings → Change** — it re-tests, applies, and restarts the daemon for you.
176
189
 
@@ -180,29 +193,28 @@ docker run -d --name sigil-pg -p 5432:5432 \
180
193
  -e POSTGRES_PASSWORD=sigil_dev pgvector/pgvector:pg15
181
194
  ```
182
195
 
183
- Finishing the wizard auto-detects every AI client on your machine (Claude Code, Codex CLI, Cursor, Kiro) and wires Sigil into each: hooks for Claude Code, MCP server registration + steering rules for the rest, plus `@~/.sigil/CLAUDE.md` in your global Claude config so hot-context is always loaded.
196
+ Choose which detected agents to connect, then enter your name to save your first memory. You can connect more agents later from the **Agents** page or with `sigil connect`.
184
197
 
185
198
  ### Prefer the terminal?
186
199
 
187
- The interactive CLI setup still works and is fully equivalent:
200
+ The installer auto-falls back to the terminal wizard when there's no browser (headless / SSH / CI). After installing, the CLI setup is fully equivalent:
188
201
  ```bash
189
- npm install -g @anmol-srv/sigil
190
202
  sigil init # interactive
191
- sigil init --url "postgres://user:pass@ep-foo.neon.tech/sigil?sslmode=require" # non-interactive (CI / dotfiles)
203
+ sigil init --url "postgres://user:pass@ep-foo.neon.tech/sigil?sslmode=require" # skips database selection
192
204
  sigil doctor # verify everything's wired
193
205
  ```
194
- Re-running `sigil init` is idempotent — existing `~/.sigil/.env` keys are preserved.
206
+ Setup saves settings in `~/.sigil/config.json`. Use `sigil connect` to refresh agent wiring for an existing setup.
195
207
  ```
196
208
  Sigil diagnostic
197
209
 
198
- ✓ Config file: ~/.sigil/.env
210
+ ✓ Config file: ~/.sigil/config.json
199
211
  ✓ Config validation: no provider/model mismatches
200
212
  ✓ Database: Postgres @ localhost:5432/sigil
201
213
  ✓ Stored data: 0 docs, 0 chunks, 0 facts
202
214
  ✓ LLM provider: openrouter (model=google/gemini-flash-latest)
203
215
  ✓ Embedding provider: openai / text-embedding-3-large
216
+ ✓ SessionStart hook: registered
204
217
  ✓ UserPromptSubmit hook: registered
205
- ✓ PostToolUse hook: registered
206
218
  ✓ Stop hook: registered
207
219
  ✓ SessionEnd hook: registered
208
220
  ✓ Sigil CLAUDE.md
@@ -221,7 +233,7 @@ sigil remember "Project uses Postgres LISTEN/NOTIFY for events, not Redis pubsub
221
233
 
222
234
  Open Claude Code in any project tomorrow. Ask "what's our event delivery setup?" and Claude answers correctly. The `UserPromptSubmit` hook injected the fact before Claude saw your prompt.
223
235
 
224
- In practice you rarely call `sigil remember` directly. The `Stop` hook runs a classifier on every user message and auto-saves anything memorable (preferences, decisions, constraints, factual claims). The `PostToolUse` hook captures observations from Edit/Write/Bash.
236
+ The Claude Code `Stop` hook classifies user messages and can save durable preferences, decisions, constraints, and facts. Use `sigil remember` to save a specific fact explicitly.
225
237
 
226
238
  ---
227
239
 
@@ -413,7 +425,7 @@ A: Single-user for now. Multiple installs sharing one Postgres works (see [Cross
413
425
  A: Your prompt still goes through. Every hook wraps in a top-level try/catch that fails silently, Sigil's invariant is **a broken memory layer must never block a working prompt.** Errors append to `~/.sigil/.hook-errors.log`; `sigil doctor` surfaces them. After 5 unacked errors in 24h, `sigil doctor` exits with code 1 so CI / scripts can catch it.
414
426
 
415
427
  **Q: How do I uninstall cleanly?**
416
- A: `npm uninstall -g @anmol-srv/sigil` removes the binary. `rm -rf ~/.sigil` removes data and config. Unwire from Claude Code by removing the sigil hook entries from `~/.claude/settings.json` and the `@~/.sigil/CLAUDE.md` line from `~/.claude/CLAUDE.md`. The Postgres database (`sigil`) and user (`sigil_app`) survive. Drop them yourself if you want them gone.
428
+ A: `rm -rf ~/.sigil` removes the install (the git clone at `~/.sigil/app`), data, and config in one shot. Remove the `export PATH="$HOME/.sigil/bin:$PATH"` line the installer added to your shell rc. Unwire from Claude Code by removing the sigil hook entries from `~/.claude/settings.json` and the `@~/.sigil/CLAUDE.md` line from `~/.claude/CLAUDE.md`. The Postgres database (`sigil`) and user (`sigil_app`) survive. Drop them yourself if you want them gone.
417
429
 
418
430
  **Q: Where can I see how the retrieval pipeline actually works?**
419
431
  A: Read `src/memory/search/hybrid.js` (entry point) and `src/memory/search/hybrid-sql.js` (the single-SQL RRF + ACT-R activation query). The pod kind registry contracts are in `src/memory/pods/kinds/`. Hooks are in `src/hooks/`.