@rbalchii/anchor-engine 4.7.0 → 4.8.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 (3) hide show
  1. package/README.md +337 -317
  2. package/engine/package.json +105 -105
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,317 +1,337 @@
1
- # Anchor Engine ⚓
2
-
3
- **Deterministic semantic memory for LLMs – local-first, graph traversal, <1GB RAM**
4
-
5
- [![GitHub release](https://img.shields.io/github/v/release/RSBalchII/anchor-engine-node)](https://github.com/RSBalchII/anchor-engine-node/releases)
6
- [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
7
- [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
8
- [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18841399.svg)](https://doi.org/10.5281/zenodo.18841399)
9
-
10
- ---
11
-
12
- ## 🌟 Why Anchor Engine?
13
-
14
- Modern AI memory is broken.
15
-
16
- Vector databases demand GPUs, gigabytes of RAM, and cloud infrastructure. They're opaque, expensive, and fundamentally incompatible with personal, local‑first AI.
17
-
18
- **Anchor Engine takes a different path.**
19
-
20
- It's a **deterministic, explainable, CPU‑only memory engine** that runs on anything—from a $200 laptop to a workstation—and retrieves context using a physics‑inspired graph algorithm instead of dense vectors.
21
-
22
- If you want:
23
- - **Local‑first AI** – your data stays yours
24
- - **Explainable retrieval** – know *why* something was returned
25
- - **Deterministic results** – same query, same answer, every time
26
- - **Zero cloud dependency** – no API keys, no servers
27
- - **<1GB RAM usage** – runs alongside your browser
28
- - **High‑speed ingestion** – 100MB in minutes
29
-
30
- …then Anchor Engine is built for you.
31
-
32
- ---
33
-
34
- ## ⚡ Quick Start (5 Minutes)
35
-
36
- ```bash
37
- # 1. Clone & Install
38
- git clone https://github.com/RSBalchII/anchor-engine-node.git
39
- cd anchor-engine-node
40
- pnpm install
41
- pnpm build
42
-
43
- # 2. Start the engine
44
- pnpm start
45
-
46
- # 3. Open your browser
47
- open http://localhost:3160
48
- ```
49
-
50
- That's it! You now have a sovereign memory system for your LLM.
51
-
52
- ---
53
-
54
- ## 📊 Anchor Engine vs. Vector RAG
55
-
56
- | Feature | Anchor Engine | Vector RAG |
57
- |---------|---------------|------------|
58
- | **Hardware** | CPU‑only | GPU preferred |
59
- | **RAM Usage** | <1GB | 4–8GB |
60
- | **Explainability** | Native (tags, hops, decay) | None (black box) |
61
- | **Deterministic** | ✅ Yes | ❌ No |
62
- | **Cloud Required** | ❌ No | Often |
63
- | **Retrieval Complexity** | O(k·d̄) linear | O(n log n) |
64
- | **License** | AGPL-3.0 (open) | Varies (often proprietary) |
65
-
66
- ---
67
-
68
- ## 🧠 The STAR Algorithm
69
-
70
- Anchor Engine uses **STAR** (Semantic Temporal Associative Retrieval)—a physics‑inspired scoring equation that combines:
71
-
72
- ```
73
- W(q,a) = |T(q) ∩ T(a)| · γ^d(q,a) × e^(−λΔt) × (1 − H(h_q, h_a)/64)
74
- ↑ Semantic Gravity ↑ Temporal Decay ↑ Structural Gravity
75
- ```
76
-
77
- | Component | What It Does |
78
- |-----------|--------------|
79
- | **Semantic Gravity** | Shared tags × hop‑distance damping (γ = 0.85) |
80
- | **Temporal Decay** | Recent memories pull harder (half-life ~115 min) |
81
- | **Structural Gravity** | SimHash proximity (64-bit fingerprints) |
82
-
83
- **Result:** O(k·d̄) retrieval—dramatically faster than vector ANN for personal datasets. Every atom includes **provenance**: shared tags, hop distance, recency, and byte‑range pointers.
84
-
85
- ---
86
-
87
- ## ⚓ Why "Anchor"?
88
-
89
- > **Drop a query into your memory graph.**
90
- > **The Anchor finds the semantic bottom.**
91
- > **The chain plays out to your chosen radius.**
92
- > **What's retrieved is what's relevant—nothing more, nothing less.**
93
- > **Same anchor, same spot, same result. Every time.**
94
- > **This isn't a metaphor. It's the algorithm.**
95
-
96
- | Anchor Quality | How It Maps to STAR |
97
- |----------------|---------------------|
98
- | **Drops to a point** | Query finds seed atoms (anchor discovery) |
99
- | **Defines a radius** | Chain length = token budget (hop distance) |
100
- | **Holds against drift** | Deterministic retrieval (no semantic drift) |
101
- | **Connects to the ship** | Retrieved context → LLM (your ship) |
102
- | **Works in deep water** | Scales from 10MB to 10GB graphs |
103
-
104
- The name isn't marketing. It's architecture.
105
-
106
- ---
107
-
108
- ## 📥 Ingest Your Data
109
-
110
- ### Option 1: Web UI (Easiest)
111
- 1. Open http://localhost:3160
112
- 2. Click **"Manage Paths"** → Add folders to watch
113
- 3. Or use **"Paste & Ingest"** tab for quick text
114
-
115
- ### Option 2: API
116
- ```bash
117
- curl -X POST http://localhost:3160/v1/research/upload-raw \
118
- -H "Content-Type: application/json" \
119
- -d '{
120
- "content": "Your text here...",
121
- "filename": "notes.md",
122
- "bucket": "inbox"
123
- }'
124
- ```
125
-
126
- ### Option 3: MCP (Claude, Cursor, Qwen Code)
127
- ```
128
- /anchor_ingest_text content="Meeting notes..." filename="meeting.md" bucket="inbox"
129
- ```
130
-
131
- ---
132
-
133
- ## 🔍 Search Your Memory
134
-
135
- ### Web UI
136
- - Natural language queries
137
- - Adjustable token budget slider
138
- - Filter by buckets/tags
139
-
140
- ### API
141
- ```bash
142
- curl -X POST http://localhost:3160/v1/memory/search \
143
- -H "Content-Type: application/json" \
144
- -d '{
145
- "query": "What did we discuss about OAuth?",
146
- "token_budget": 2048
147
- }'
148
- ```
149
-
150
- ### MCP Tools
151
- ```
152
- /anchor_query query="OAuth authentication setup"
153
- /anchor_search_index query="career planning"
154
- /anchor_fetch_session session_id="abc-123"
155
- ```
156
-
157
- ---
158
-
159
- ## 🏛️ Our Philosophy: AI Memory Should Work Like Your Brain
160
-
161
- Human memory is remarkably efficient. It runs on ~20 watts, forgets irrelevant details, and over time clarifies core truths rather than drowning in noise. It doesn't store raw experiences—it stores *patterns*, *relationships*, and *meaning*.
162
-
163
- Most AI memory systems do the opposite: they hoard data, brute‑force compute similarity, and require massive infrastructure.
164
-
165
- **Anchor Engine was built on a different premise: AI memory should work like the human mind—lightweight, connected, and self‑clarifying.**
166
-
167
- | Principle | What It Means | How Anchor Implements It |
168
- |-----------|---------------|--------------------------|
169
- | **🧠 Forgetting is a feature** | The brain forgets constantly, leaving only what matters | `distill:` command removes redundancy; temporal decay |
170
- | **🔗 Meaning lives in relationships** | We store how concepts connect, not isolated facts | Graph model with typed edges; STAR algorithm |
171
- | **⚡ Low power, high efficiency** | The brain achieves its magic on ~20 watts | Pointer‑only database; content on disk; <1GB RAM |
172
- | **💎 Clarity through distillation** | Memory builds higher‑level abstractions over time | Decision Records v2.0 extract the *why* |
173
- | **🔍 Explainability builds trust** | You know *why* a memory came to mind | Provenance tracking; receipts with timestamps |
174
-
175
- > **Why This Matters:** Most AI memory systems are built for **scale**, not for **sense**. Anchor Engine is designed for **sense‑making**—for agents that need to remember not just *what* happened, but *why*, and to get *clearer* over time.
176
-
177
- ---
178
-
179
- ## 🏗️ Architecture at a Glance
180
-
181
- ```
182
- ┌─────────────────────────────────────────────────────────────┐
183
- │ YOU │
184
- └────────────────────┬────────────────────────────────────────┘
185
- │
186
- ▼
187
- ┌─────────────────────────────────────────────────────────────┐
188
- │ ⚡ ANCHOR ENGINE │
189
- │ (Deterministic Memory Layer) │
190
- │ │
191
- │ - Graph traversal (STAR algorithm) │
192
- │ - Pointer-only index (<1GB RAM) │
193
- │ - Deterministic retrieval (same query = same result) │
194
- └────────────────────┬────────────────────────────────────────┘
195
- │
196
- ┌───────────┼───────────┐
197
- │ │ │
198
- ▼ ▼ ▼
199
- ┌──────────────┐ ┌──────────┐ ┌─────────────┐
200
- │ PGlite │ │ mirrored │ │ MCP Clients │
201
- │ (WASM DB) │ │ _brain/ │ │ (Claude, │
202
- │ │ │ (Content)│ │ Cursor) │
203
- └──────────────┘ └──────────┘ └─────────────┘
204
- ```
205
-
206
- **Key Insight:** Content lives in `mirrored_brain/` filesystem. Database stores **pointers only** (byte offsets + metadata). This makes the database **disposable and rebuildable**—wipe it and restore in minutes.
207
-
208
- ---
209
-
210
- ## 📊 Benchmarks (Real Production Data)
211
-
212
- **Dataset:** 91MB chat history (~25M tokens)
213
-
214
- | Metric | Result |
215
- |--------|--------|
216
- | **Molecules** | 280,000 |
217
- | **Atoms** | 151,876 |
218
- | **Files** | 436 |
219
- | **Ingestion Time** | 178 seconds |
220
- | **Search Latency (p95)** | <200ms |
221
- | **Memory (idle)** | ~600MB |
222
- | **Memory (peak)** | ~1.6GB |
223
- | **Restore Speed** | 281,690 atoms in 13.8 min |
224
-
225
- **Hardware:** AMD Ryzen / Intel i7, 16GB RAM, NVMe SSD, no GPU.
226
-
227
- ---
228
-
229
- ## 🛠️ What's New in v4.8.0
230
-
231
- ### MCP Write Operations
232
- - **`anchor_ingest_text`** - Ingest raw text directly
233
- - **`anchor_ingest_file`** - Ingest files from filesystem
234
- - Security toggle (opt-in via `user_settings.json`)
235
-
236
- ### Session Index
237
- - **`anchor_search_index`** - Fast chat session lookup
238
- - **`anchor_fetch_session`** - Targeted session retrieval
239
- - Two-tier memory retrieval
240
-
241
- ### Web UI Improvements
242
- - **Paste & Ingest** tab - Quick text ingestion
243
- - Version badge (v4.8.0)
244
- - Bucket selector (inbox vs external-inbox)
245
-
246
- ### Documentation Overhaul
247
- - 5 new docs (API, Deployment, Troubleshooting, Source Overview, Testing)
248
- - Philosophy embedded throughout
249
- - 7 redundant files archived
250
-
251
- ---
252
-
253
- ## 📚 Documentation
254
-
255
- ### Getting Started
256
- - **[Quick Start](#-quick-start-5-minutes)** - Install & first query
257
- - **[docs/API.md](docs/API.md)** - Complete API reference
258
- - **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)** - Deployment guide (local, Docker, VPS, K8s)
259
- - **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - Common issues & fixes
260
-
261
- ### Deep Dive
262
- - **[docs/whitepaper.md](docs/whitepaper.md)** - STAR algorithm whitepaper
263
- - **[specs/spec.md](specs/spec.md)** - System specification with diagrams
264
- - **[specs/current-standards/](specs/current-standards/)** - Active standards (001-010)
265
- - **[engine/src/README.md](engine/src/README.md)** - Source code overview
266
-
267
- ### Integration
268
- - **[mcp-server/README.md](mcp-server/README.md)** - MCP integration (Claude, Cursor, Qwen)
269
- - **[tests/README.md](tests/README.md)** - Testing guide
270
- - **[benchmarks/README.md](benchmarks/README.md)** - Performance benchmarks
271
-
272
- ---
273
-
274
- ## 🤝 Contributing
275
-
276
- We're building in the open and welcome your input!
277
-
278
- - **Star the repo** – Helps others find it
279
- - **Open an issue** – Bugs, features, questions
280
- - **Start a discussion** – Share use cases
281
- - **Contribute** – PRs welcome!
282
-
283
- See [`CONTRIBUTING.md`](CONTRIBUTING.md) for guidelines.
284
-
285
- **Community Health:**
286
- - [`CODEOWNERS`](.github/CODEOWNERS) - Automatic reviewer assignment
287
- - [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) - Community standards
288
- - [`CONTRIBUTING.md`](CONTRIBUTING.md) - Contribution guide
289
-
290
- ---
291
-
292
- ## 📜 License
293
-
294
- AGPL-3.0 – see [LICENSE](LICENSE).
295
-
296
- ---
297
-
298
- ## 🙏 Acknowledgments
299
-
300
- Built with ❤️ by Robert Balch II and contributors.
301
- Inspired by the r/LocalLLaMA and r/aiagents communities.
302
-
303
- **Citation:**
304
- ```bibtex
305
- @software{anchor_engine,
306
- title = {STAR: Semantic Temporal Associative Retrieval},
307
- author = {Balch II, R.S.},
308
- version = {4.8.0},
309
- date = {2026-03-18},
310
- url = {https://github.com/RSBalchII/anchor-engine-node},
311
- doi = {10.5281/zenodo.18841399}
312
- }
313
- ```
314
-
315
- ---
316
-
317
- *Your AI's anchor to reality.* ⚓
1
+ # Anchor Engine ⚓
2
+
3
+ **Deterministic semantic memory for LLMs – local-first, graph traversal, <1GB RAM**
4
+
5
+ [![GitHub release](https://img.shields.io/github/v/release/RSBalchII/anchor-engine-node)](https://github.com/RSBalchII/anchor-engine-node/releases)
6
+ [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
7
+ [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
8
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18841399.svg)](https://doi.org/10.5281/zenodo.18841399)
9
+
10
+ ---
11
+
12
+ ## 🌟 Why Anchor Engine?
13
+
14
+ Modern AI memory is broken.
15
+
16
+ Vector databases demand GPUs, gigabytes of RAM, and cloud infrastructure. They're opaque, expensive, and fundamentally incompatible with personal, local‑first AI.
17
+
18
+ **Anchor Engine takes a different path.**
19
+
20
+ It's a **deterministic, explainable, CPU‑only memory engine** that runs on anything—from a $200 laptop to a workstation—and retrieves context using a physics‑inspired graph algorithm instead of dense vectors.
21
+
22
+ If you want:
23
+ - **Local‑first AI** – your data stays yours
24
+ - **Explainable retrieval** – know *why* something was returned
25
+ - **Deterministic results** – same query, same answer, every time
26
+ - **Zero cloud dependency** – no API keys, no servers
27
+ - **<1GB RAM usage** – runs alongside your browser
28
+ - **High‑speed ingestion** – 100MB in minutes
29
+
30
+ …then Anchor Engine is built for you.
31
+
32
+ ---
33
+
34
+ ## ⚡ Quick Start (5 Minutes)
35
+
36
+ ### Option 1: npm Install (Recommended)
37
+
38
+ ```bash
39
+ # Install the package
40
+ npm install @rbalchii/anchor-engine
41
+
42
+ # Or globally for CLI access
43
+ npm install -g @rbalchii/anchor-engine
44
+
45
+ # Start the engine
46
+ anchor start
47
+
48
+ # Open your browser
49
+ open http://localhost:3160
50
+ ```
51
+
52
+ ### Option 2: From Source
53
+
54
+ ```bash
55
+ # 1. Clone & Install
56
+ git clone https://github.com/RSBalchII/anchor-engine-node.git
57
+ cd anchor-engine-node
58
+ pnpm install
59
+ pnpm build
60
+
61
+ # 2. Start the engine
62
+ pnpm start
63
+
64
+ # 3. Open your browser
65
+ open http://localhost:3160
66
+ ```
67
+
68
+ That's it! You now have a sovereign memory system for your LLM.
69
+
70
+ **Full installation guide:** [INSTALL_NPM.md](INSTALL_NPM.md)
71
+
72
+ ---
73
+
74
+ ## 📊 Anchor Engine vs. Vector RAG
75
+
76
+ | Feature | Anchor Engine | Vector RAG |
77
+ |---------|---------------|------------|
78
+ | **Hardware** | CPU‑only | GPU preferred |
79
+ | **RAM Usage** | <1GB | 4–8GB |
80
+ | **Explainability** | Native (tags, hops, decay) | None (black box) |
81
+ | **Deterministic** | ✅ Yes | ❌ No |
82
+ | **Cloud Required** | ❌ No | Often |
83
+ | **Retrieval Complexity** | O(k·d̄) linear | O(n log n) |
84
+ | **License** | AGPL-3.0 (open) | Varies (often proprietary) |
85
+
86
+ ---
87
+
88
+ ## 🧠 The STAR Algorithm
89
+
90
+ Anchor Engine uses **STAR** (Semantic Temporal Associative Retrieval)—a physics‑inspired scoring equation that combines:
91
+
92
+ ```
93
+ W(q,a) = |T(q) ∩ T(a)| · γ^d(q,a) × e^(−λΔt) × (1 − H(h_q, h_a)/64)
94
+ ↑ Semantic Gravity ↑ Temporal Decay ↑ Structural Gravity
95
+ ```
96
+
97
+ | Component | What It Does |
98
+ |-----------|--------------|
99
+ | **Semantic Gravity** | Shared tags × hop‑distance damping (γ = 0.85) |
100
+ | **Temporal Decay** | Recent memories pull harder (half-life ~115 min) |
101
+ | **Structural Gravity** | SimHash proximity (64-bit fingerprints) |
102
+
103
+ **Result:** O(k·d̄) retrieval—dramatically faster than vector ANN for personal datasets. Every atom includes **provenance**: shared tags, hop distance, recency, and byte‑range pointers.
104
+
105
+ ---
106
+
107
+ ## ⚓ Why "Anchor"?
108
+
109
+ > **Drop a query into your memory graph.**
110
+ > **The Anchor finds the semantic bottom.**
111
+ > **The chain plays out to your chosen radius.**
112
+ > **What's retrieved is what's relevant—nothing more, nothing less.**
113
+ > **Same anchor, same spot, same result. Every time.**
114
+ > **This isn't a metaphor. It's the algorithm.**
115
+
116
+ | Anchor Quality | How It Maps to STAR |
117
+ |----------------|---------------------|
118
+ | **Drops to a point** | Query finds seed atoms (anchor discovery) |
119
+ | **Defines a radius** | Chain length = token budget (hop distance) |
120
+ | **Holds against drift** | Deterministic retrieval (no semantic drift) |
121
+ | **Connects to the ship** | Retrieved context → LLM (your ship) |
122
+ | **Works in deep water** | Scales from 10MB to 10GB graphs |
123
+
124
+ The name isn't marketing. It's architecture.
125
+
126
+ ---
127
+
128
+ ## 📥 Ingest Your Data
129
+
130
+ ### Option 1: Web UI (Easiest)
131
+ 1. Open http://localhost:3160
132
+ 2. Click **"Manage Paths"** → Add folders to watch
133
+ 3. Or use **"Paste & Ingest"** tab for quick text
134
+
135
+ ### Option 2: API
136
+ ```bash
137
+ curl -X POST http://localhost:3160/v1/research/upload-raw \
138
+ -H "Content-Type: application/json" \
139
+ -d '{
140
+ "content": "Your text here...",
141
+ "filename": "notes.md",
142
+ "bucket": "inbox"
143
+ }'
144
+ ```
145
+
146
+ ### Option 3: MCP (Claude, Cursor, Qwen Code)
147
+ ```
148
+ /anchor_ingest_text content="Meeting notes..." filename="meeting.md" bucket="inbox"
149
+ ```
150
+
151
+ ---
152
+
153
+ ## 🔍 Search Your Memory
154
+
155
+ ### Web UI
156
+ - Natural language queries
157
+ - Adjustable token budget slider
158
+ - Filter by buckets/tags
159
+
160
+ ### API
161
+ ```bash
162
+ curl -X POST http://localhost:3160/v1/memory/search \
163
+ -H "Content-Type: application/json" \
164
+ -d '{
165
+ "query": "What did we discuss about OAuth?",
166
+ "token_budget": 2048
167
+ }'
168
+ ```
169
+
170
+ ### MCP Tools
171
+ ```
172
+ /anchor_query query="OAuth authentication setup"
173
+ /anchor_search_index query="career planning"
174
+ /anchor_fetch_session session_id="abc-123"
175
+ ```
176
+
177
+ ---
178
+
179
+ ## 🏛️ Our Philosophy: AI Memory Should Work Like Your Brain
180
+
181
+ Human memory is remarkably efficient. It runs on ~20 watts, forgets irrelevant details, and over time clarifies core truths rather than drowning in noise. It doesn't store raw experiences—it stores *patterns*, *relationships*, and *meaning*.
182
+
183
+ Most AI memory systems do the opposite: they hoard data, brute‑force compute similarity, and require massive infrastructure.
184
+
185
+ **Anchor Engine was built on a different premise: AI memory should work like the human mind—lightweight, connected, and self‑clarifying.**
186
+
187
+ | Principle | What It Means | How Anchor Implements It |
188
+ |-----------|---------------|--------------------------|
189
+ | **🧠 Forgetting is a feature** | The brain forgets constantly, leaving only what matters | `distill:` command removes redundancy; temporal decay |
190
+ | **🔗 Meaning lives in relationships** | We store how concepts connect, not isolated facts | Graph model with typed edges; STAR algorithm |
191
+ | **⚡ Low power, high efficiency** | The brain achieves its magic on ~20 watts | Pointer‑only database; content on disk; <1GB RAM |
192
+ | **💎 Clarity through distillation** | Memory builds higher‑level abstractions over time | Decision Records v2.0 extract the *why* |
193
+ | **🔍 Explainability builds trust** | You know *why* a memory came to mind | Provenance tracking; receipts with timestamps |
194
+
195
+ > **Why This Matters:** Most AI memory systems are built for **scale**, not for **sense**. Anchor Engine is designed for **sense‑making**—for agents that need to remember not just *what* happened, but *why*, and to get *clearer* over time.
196
+
197
+ ---
198
+
199
+ ## 🏗️ Architecture at a Glance
200
+
201
+ ```
202
+ ┌─────────────────────────────────────────────────────────────┐
203
+ │ YOU │
204
+ └────────────────────┬────────────────────────────────────────┘
205
+ │
206
+ ▼
207
+ ┌─────────────────────────────────────────────────────────────┐
208
+ │ ⚡ ANCHOR ENGINE │
209
+ │ (Deterministic Memory Layer) │
210
+ │ │
211
+ │ - Graph traversal (STAR algorithm) │
212
+ │ - Pointer-only index (<1GB RAM) │
213
+ │ - Deterministic retrieval (same query = same result) │
214
+ └────────────────────┬────────────────────────────────────────┘
215
+ │
216
+ ┌───────────┼───────────┐
217
+ │ │ │
218
+ ▼ ▼ ▼
219
+ ┌──────────────┐ ┌──────────┐ ┌─────────────┐
220
+ │ PGlite │ │ mirrored │ │ MCP Clients │
221
+ │ (WASM DB) │ │ _brain/ │ │ (Claude, │
222
+ │ │ │ (Content)│ │ Cursor) │
223
+ └──────────────┘ └──────────┘ └─────────────┘
224
+ ```
225
+
226
+ **Key Insight:** Content lives in `mirrored_brain/` filesystem. Database stores **pointers only** (byte offsets + metadata). This makes the database **disposable and rebuildable**—wipe it and restore in minutes.
227
+
228
+ ---
229
+
230
+ ## 📊 Benchmarks (Real Production Data)
231
+
232
+ **Dataset:** 91MB chat history (~25M tokens)
233
+
234
+ | Metric | Result |
235
+ |--------|--------|
236
+ | **Molecules** | 280,000 |
237
+ | **Atoms** | 151,876 |
238
+ | **Files** | 436 |
239
+ | **Ingestion Time** | 178 seconds |
240
+ | **Search Latency (p95)** | <200ms |
241
+ | **Memory (idle)** | ~600MB |
242
+ | **Memory (peak)** | ~1.6GB |
243
+ | **Restore Speed** | 281,690 atoms in 13.8 min |
244
+
245
+ **Hardware:** AMD Ryzen / Intel i7, 16GB RAM, NVMe SSD, no GPU.
246
+
247
+ ---
248
+
249
+ ## 🛠️ What's New in v4.8.0
250
+
251
+ ### MCP Write Operations
252
+ - **`anchor_ingest_text`** - Ingest raw text directly
253
+ - **`anchor_ingest_file`** - Ingest files from filesystem
254
+ - Security toggle (opt-in via `user_settings.json`)
255
+
256
+ ### Session Index
257
+ - **`anchor_search_index`** - Fast chat session lookup
258
+ - **`anchor_fetch_session`** - Targeted session retrieval
259
+ - Two-tier memory retrieval
260
+
261
+ ### Web UI Improvements
262
+ - **Paste & Ingest** tab - Quick text ingestion
263
+ - Version badge (v4.8.0)
264
+ - Bucket selector (inbox vs external-inbox)
265
+
266
+ ### Documentation Overhaul
267
+ - 5 new docs (API, Deployment, Troubleshooting, Source Overview, Testing)
268
+ - Philosophy embedded throughout
269
+ - 7 redundant files archived
270
+
271
+ ---
272
+
273
+ ## 📚 Documentation
274
+
275
+ ### Getting Started
276
+ - **[Quick Start](#-quick-start-5-minutes)** - Install & first query
277
+ - **[docs/API.md](docs/API.md)** - Complete API reference
278
+ - **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)** - Deployment guide (local, Docker, VPS, K8s)
279
+ - **[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - Common issues & fixes
280
+
281
+ ### Deep Dive
282
+ - **[docs/whitepaper.md](docs/whitepaper.md)** - STAR algorithm whitepaper
283
+ - **[specs/spec.md](specs/spec.md)** - System specification with diagrams
284
+ - **[specs/current-standards/](specs/current-standards/)** - Active standards (001-010)
285
+ - **[engine/src/README.md](engine/src/README.md)** - Source code overview
286
+
287
+ ### Integration
288
+ - **[mcp-server/README.md](mcp-server/README.md)** - MCP integration (Claude, Cursor, Qwen)
289
+ - **[tests/README.md](tests/README.md)** - Testing guide
290
+ - **[benchmarks/README.md](benchmarks/README.md)** - Performance benchmarks
291
+
292
+ ---
293
+
294
+ ## 🤝 Contributing
295
+
296
+ We're building in the open and welcome your input!
297
+
298
+ - **Star the repo** – Helps others find it
299
+ - **Open an issue** – Bugs, features, questions
300
+ - **Start a discussion** – Share use cases
301
+ - **Contribute** – PRs welcome!
302
+
303
+ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for guidelines.
304
+
305
+ **Community Health:**
306
+ - [`CODEOWNERS`](.github/CODEOWNERS) - Automatic reviewer assignment
307
+ - [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) - Community standards
308
+ - [`CONTRIBUTING.md`](CONTRIBUTING.md) - Contribution guide
309
+
310
+ ---
311
+
312
+ ## 📜 License
313
+
314
+ AGPL-3.0 – see [LICENSE](LICENSE).
315
+
316
+ ---
317
+
318
+ ## 🙏 Acknowledgments
319
+
320
+ Built with ❤️ by Robert Balch II and contributors.
321
+ Inspired by the r/LocalLLaMA and r/aiagents communities.
322
+
323
+ **Citation:**
324
+ ```bibtex
325
+ @software{anchor_engine,
326
+ title = {STAR: Semantic Temporal Associative Retrieval},
327
+ author = {Balch II, R.S.},
328
+ version = {4.8.0},
329
+ date = {2026-03-18},
330
+ url = {https://github.com/RSBalchII/anchor-engine-node},
331
+ doi = {10.5281/zenodo.18841399}
332
+ }
333
+ ```
334
+
335
+ ---
336
+
337
+ *Your AI's anchor to reality.* ⚓
package/engine/package.json CHANGED
@@ -1,105 +1,105 @@
1
- {
2
- "name": "anchor-engine",
3
- "version": "4.6.0",
4
- "type": "module",
5
- "description": "Anchor Headless Context Engine & Knowledge Graph",
6
- "main": "src/index.js",
7
- "bin": "src/index.js",
8
- "scripts": {
9
- "start": "node --expose-gc dist/index.js",
10
- "dev": "node --loader ts-node/esm src/index.ts",
11
- "migrate": "node src/migrate_history.js",
12
- "read-all": "node src/read_all.js",
13
- "hydrate": "node src/hydrate.js",
14
- "test:vitest": "vitest run --config vitest.config.ts",
15
- "test:vitest:watch": "vitest --config vitest.config.ts",
16
- "test": "node tests/suite.js",
17
- "test:routes": "node tests/all_routes_and_services.js",
18
- "test:quick": "node tests/suite.js",
19
- "test:benchmark": "node tests/benchmark.js",
20
- "test:context": "node tests/context_experiments.js",
21
- "test:context-quality": "ts-node ../tests/unit/test_context_quality_improvements.ts",
22
- "test:date-extractor": "node --loader ts-node/esm tests/unit/test_date_extractor.ts",
23
- "test:unit": "ts-node ../tests/unit/test_context_quality_improvements.ts",
24
- "test:vector": "node --loader ts-node/esm tests/unit/test_vector_service.ts",
25
- "benchmark": "node tests/benchmark.js",
26
- "build": "node -e \"require('fs').rmSync('dist', {recursive:true, force:true})\" && tsc",
27
- "build:npm-native": "echo \"Native modules now handled via npm packages\"",
28
- "build:standalone": "node -e \"require('fs').rmSync('dist', {recursive:true, force:true})\" && tsc && pkg dist/index.js --target node18-linux-arm64 --output dist-android/anchor-engine --compress GZip && pkg dist/index.js --target node18-win-x64 --output dist-win/anchor-engine.exe --compress GZip",
29
- "build:win": "node -e \"require('fs').rmSync('dist', {recursive:true, force:true})\" && tsc && pkg dist/index.js --target node18-win-x64 --output dist-win/anchor-engine.exe --compress GZip",
30
- "build:android": "node -e \"require('fs').rmSync('dist', {recursive:true, force:true})\" && tsc && pkg dist/index.js --target node18-linux-arm64 --output dist-android/anchor-engine --compress GZip",
31
- "build:universal": "npm run build",
32
- "lint": "eslint src/ --ext .ts,.js",
33
- "chat": "ts-node tools/chat.ts",
34
- "chat-api": "node dist/server-8080.js",
35
- "lint:fix": "eslint src/ --ext .ts,.js --fix",
36
- "generate-synonyms": "node --loader ts-node/esm src/commands/generate-synonyms.ts",
37
- "audit-tags": "node --loader ts-node/esm src/commands/audit-tags.ts",
38
- "distill": "node --loader ts-node/esm src/commands/distill.ts"
39
- },
40
- "pkg": {
41
- "scripts": [
42
- "dist/**/*.js"
43
- ],
44
- "assets": [
45
- "dist/**/*",
46
- "context_data/**/*",
47
- "user_settings.json",
48
- "node_modules/@electric-sql/pglite/**/*",
49
- "node_modules/@rbalchii/anchor-atomizer-wasm/**/*",
50
- "node_modules/@rbalchii/anchor-fingerprint-wasm/**/*",
51
- "node_modules/@rbalchii/anchor-keyextract-wasm/**/*",
52
- "node_modules/@rbalchii/anchor-tagwalker-wasm/**/*",
53
- "node_modules/wink-eng-lite-web-model/**/*",
54
- "node_modules/wink-nlp/**/*"
55
- ],
56
- "targets": [
57
- "node18-linux-arm64"
58
- ],
59
- "outputPath": "dist-android",
60
- "compress": "GZip"
61
- },
62
- "dependencies": {
63
- "@anchor/shared": "file:../shared",
64
- "@electric-sql/pglite": "^0.2.0",
65
- "@modelcontextprotocol/sdk": "^1.27.1",
66
- "@rbalchii/anchor-atomizer-wasm": "^1.0.0",
67
- "@rbalchii/anchor-fingerprint-wasm": "^1.0.0",
68
- "@rbalchii/anchor-keyextract-wasm": "^1.0.0",
69
- "@rbalchii/anchor-tagwalker-wasm": "^1.0.0",
70
- "@rbalchii/dse": "^1.0.0",
71
- "@types/body-parser": "^1.19.6",
72
- "@types/turndown": "^5.0.6",
73
- "axios": "^1.13.2",
74
- "body-parser": "^1.20.2",
75
- "cheerio": "^1.1.2",
76
- "chokidar": "^3.6.0",
77
- "cors": "^2.8.5",
78
- "express": "^4.18.2",
79
- "express-rate-limit": "^7.4.0",
80
- "got": "^14.6.6",
81
- "got-scraping": "^4.1.3",
82
- "js-yaml": "^4.1.1",
83
- "sharp": "^0.34.5",
84
- "tar": "^7.5.10",
85
- "turndown": "^7.2.2",
86
- "uuid": "^13.0.0",
87
- "wink-eng-lite-web-model": "^1.7.1",
88
- "wink-nlp": "^2.3.0",
89
- "winston": "^3.19.0",
90
- "winston-daily-rotate-file": "^5.0.0",
91
- "zod": "^4.3.6"
92
- },
93
- "devDependencies": {
94
- "@types/cors": "^2.8.19",
95
- "@types/express": "^5.0.6",
96
- "@types/js-yaml": "^4.0.9",
97
- "@types/node": "^25.0.7",
98
- "@types/tar": "^6.1.13",
99
- "@yao-pkg/pkg": "^5.12.0",
100
- "eslint": "^8.56.0",
101
- "ts-node": "^10.9.2",
102
- "typescript": "^5.9.3",
103
- "vitest": "^4.0.18"
104
- }
105
- }
1
+ {
2
+ "name": "anchor-engine",
3
+ "version": "4.8.0",
4
+ "type": "module",
5
+ "description": "Anchor Headless Context Engine & Knowledge Graph",
6
+ "main": "src/index.js",
7
+ "bin": "src/index.js",
8
+ "scripts": {
9
+ "start": "node --expose-gc dist/index.js",
10
+ "dev": "node --loader ts-node/esm src/index.ts",
11
+ "migrate": "node src/migrate_history.js",
12
+ "read-all": "node src/read_all.js",
13
+ "hydrate": "node src/hydrate.js",
14
+ "test:vitest": "vitest run --config vitest.config.ts",
15
+ "test:vitest:watch": "vitest --config vitest.config.ts",
16
+ "test": "node tests/suite.js",
17
+ "test:routes": "node tests/all_routes_and_services.js",
18
+ "test:quick": "node tests/suite.js",
19
+ "test:benchmark": "node tests/benchmark.js",
20
+ "test:context": "node tests/context_experiments.js",
21
+ "test:context-quality": "ts-node ../tests/unit/test_context_quality_improvements.ts",
22
+ "test:date-extractor": "node --loader ts-node/esm tests/unit/test_date_extractor.ts",
23
+ "test:unit": "ts-node ../tests/unit/test_context_quality_improvements.ts",
24
+ "test:vector": "node --loader ts-node/esm tests/unit/test_vector_service.ts",
25
+ "benchmark": "node tests/benchmark.js",
26
+ "build": "node -e \"require('fs').rmSync('dist', {recursive:true, force:true})\" && tsc",
27
+ "build:npm-native": "echo \"Native modules now handled via npm packages\"",
28
+ "build:standalone": "node -e \"require('fs').rmSync('dist', {recursive:true, force:true})\" && tsc && pkg dist/index.js --target node18-linux-arm64 --output dist-android/anchor-engine --compress GZip && pkg dist/index.js --target node18-win-x64 --output dist-win/anchor-engine.exe --compress GZip",
29
+ "build:win": "node -e \"require('fs').rmSync('dist', {recursive:true, force:true})\" && tsc && pkg dist/index.js --target node18-win-x64 --output dist-win/anchor-engine.exe --compress GZip",
30
+ "build:android": "node -e \"require('fs').rmSync('dist', {recursive:true, force:true})\" && tsc && pkg dist/index.js --target node18-linux-arm64 --output dist-android/anchor-engine --compress GZip",
31
+ "build:universal": "npm run build",
32
+ "lint": "eslint src/ --ext .ts,.js",
33
+ "chat": "ts-node tools/chat.ts",
34
+ "chat-api": "node dist/server-8080.js",
35
+ "lint:fix": "eslint src/ --ext .ts,.js --fix",
36
+ "generate-synonyms": "node --loader ts-node/esm src/commands/generate-synonyms.ts",
37
+ "audit-tags": "node --loader ts-node/esm src/commands/audit-tags.ts",
38
+ "distill": "node --loader ts-node/esm src/commands/distill.ts"
39
+ },
40
+ "pkg": {
41
+ "scripts": [
42
+ "dist/**/*.js"
43
+ ],
44
+ "assets": [
45
+ "dist/**/*",
46
+ "context_data/**/*",
47
+ "user_settings.json",
48
+ "node_modules/@electric-sql/pglite/**/*",
49
+ "node_modules/@rbalchii/anchor-atomizer-wasm/**/*",
50
+ "node_modules/@rbalchii/anchor-fingerprint-wasm/**/*",
51
+ "node_modules/@rbalchii/anchor-keyextract-wasm/**/*",
52
+ "node_modules/@rbalchii/anchor-tagwalker-wasm/**/*",
53
+ "node_modules/wink-eng-lite-web-model/**/*",
54
+ "node_modules/wink-nlp/**/*"
55
+ ],
56
+ "targets": [
57
+ "node18-linux-arm64"
58
+ ],
59
+ "outputPath": "dist-android",
60
+ "compress": "GZip"
61
+ },
62
+ "dependencies": {
63
+ "@anchor/shared": "file:../shared",
64
+ "@electric-sql/pglite": "^0.2.0",
65
+ "@modelcontextprotocol/sdk": "^1.27.1",
66
+ "@rbalchii/anchor-atomizer-wasm": "^1.0.0",
67
+ "@rbalchii/anchor-fingerprint-wasm": "^1.0.0",
68
+ "@rbalchii/anchor-keyextract-wasm": "^1.0.0",
69
+ "@rbalchii/anchor-tagwalker-wasm": "^1.0.0",
70
+ "@rbalchii/dse": "^1.0.0",
71
+ "@types/body-parser": "^1.19.6",
72
+ "@types/turndown": "^5.0.6",
73
+ "axios": "^1.13.2",
74
+ "body-parser": "^1.20.2",
75
+ "cheerio": "^1.1.2",
76
+ "chokidar": "^3.6.0",
77
+ "cors": "^2.8.5",
78
+ "express": "^4.18.2",
79
+ "express-rate-limit": "^7.4.0",
80
+ "got": "^14.6.6",
81
+ "got-scraping": "^4.1.3",
82
+ "js-yaml": "^4.1.1",
83
+ "sharp": "^0.34.5",
84
+ "tar": "^7.5.10",
85
+ "turndown": "^7.2.2",
86
+ "uuid": "^13.0.0",
87
+ "wink-eng-lite-web-model": "^1.7.1",
88
+ "wink-nlp": "^2.3.0",
89
+ "winston": "^3.19.0",
90
+ "winston-daily-rotate-file": "^5.0.0",
91
+ "zod": "^4.3.6"
92
+ },
93
+ "devDependencies": {
94
+ "@types/cors": "^2.8.19",
95
+ "@types/express": "^5.0.6",
96
+ "@types/js-yaml": "^4.0.9",
97
+ "@types/node": "^25.0.7",
98
+ "@types/tar": "^6.1.13",
99
+ "@yao-pkg/pkg": "^5.12.0",
100
+ "eslint": "^8.56.0",
101
+ "ts-node": "^10.9.2",
102
+ "typescript": "^5.9.3",
103
+ "vitest": "^4.0.18"
104
+ }
105
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rbalchii/anchor-engine",
3
- "version": "4.7.0",
3
+ "version": "4.8.0",
4
4
  "description": "Deterministic semantic memory for LLMs - local-first, graph traversal, <1GB RAM",
5
5
  "main": "engine/dist/index.js",
6
6
  "type": "module",