@wipcomputer/memory-crystal 0.7.28 → 0.7.29

package/CHANGELOG.md

@@ -19,6 +19,37 @@
 
 
 
+## 0.7.29 (2026-03-20)
+
+# Release Notes: memory-crystal v0.7.29
+
+**Doc audit: MLX setup, deep search params, log paths, role clarification.**
+
+## What changed
+
+SKILL.md and TECHNICAL.md updated for 2 weeks of undocumented features:
+
+- **MLX local LLM:** Added as Option A in SKILL.md Step 2. CLI commands (setup, status, stop) added to TECHNICAL.md.
+- **Deep search parameters:** `--intent`, `--explain`, `--candidates` documented in both SKILL.md (crystal_search tool) and TECHNICAL.md (CLI reference + new sections for intent, explain, candidate limit, LLM cache).
+- **Log paths:** Fixed obsolete `/tmp/ldm-dev-tools/` reference to `~/.ldm/logs/`. Added logs/ to directory structure.
+- **Role clarification:** Two-role architecture (Core and Node) explicitly stated. Standalone role was removed in v0.7.22.
+
+## Why
+
+29 releases in 13 days. Docs didn't keep pace. Agents using crystal_search didn't know about --intent (query disambiguation) or --explain (scoring transparency).
+
+## Issues closed
+
+- #57
+
+## How to verify
+
+```bash
+grep "intent" SKILL.md TECHNICAL.md
+grep "mlx" SKILL.md TECHNICAL.md
+grep "ldm/logs" TECHNICAL.md
+```
+
 ## 0.7.28 (2026-03-18)
 
 # Release Notes: memory-crystal v0.7.28

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: wip-memory-crystal
 description: Search and manage the shared memory crystal. Use when user says "do you remember", "search memory", "remember this", "forget that", "memory status", "what do you know about", or needs to recall past discussions, store facts, or check what's in memory.
-version: "0.7.28"
+version: "0.7.29"
 ---
 
 # Memory Crystal
@@ -140,7 +140,13 @@ If that returns a key, skip to Step 3.
 
 If not, ask the user which provider they want:
 
-**Option A: OpenAI (recommended, requires API key)**
+**Option A: MLX (free, local, Apple Silicon only)**
+```bash
+crystal mlx setup
+```
+Auto-installs Qwen2.5-3B on M-series Macs. Creates a LaunchAgent on port 18791. `crystal init` detects MLX automatically.
+
+**Option B: OpenAI (recommended for non-Apple Silicon, requires API key)**
 Tell the user to add this to their shell profile (`~/.zshrc` or `~/.bashrc`):
 ```bash
 export OPENAI_API_KEY="sk-..."
@@ -365,7 +371,7 @@ This machine is now a Crystal Node. Conversations are captured, encrypted, and r
 
 ## Role Management
 
-Users can check and change roles at any time:
+Two-role architecture: **Core** (master database, embedding server, relay sync) and **Node** (mirrors Core, syncs via relay, local search). Users can check and change roles at any time:
 
 ```bash
 crystal role              # Show current role
@@ -404,8 +410,12 @@ Search across all stored memory. Semantic search with recency-weighted results.
 ```
 crystal_search query="how do plugins work" limit=5
 crystal_search query="user preferences" agent_id="main"
+crystal_search query="security" intent="1Password"
+crystal_search query="deployment" time_filter="7d" explain=true
 ```
 
+Parameters: `query` (required), `limit`, `agent_id`, `time_filter` (24h/7d/30d), `intent` (disambiguate without adding search terms), `candidates` (rerank pool size), `explain` (show scoring breakdown).
+
 Results are ranked by relevance and freshness, with color-coded freshness indicators:
 - fresh (less than 3 days)
 - recent (less than 7 days)

package/TECHNICAL.md

@@ -44,7 +44,7 @@ crystal init                    # Scaffolds ~/.ldm/, deploys capture script, ins
 
 This copies `crystal-capture.sh` to `~/.ldm/bin/` and installs a cron entry:
 ```
-* * * * * ~/.ldm/bin/crystal-capture.sh >> /tmp/ldm-dev-tools/crystal-capture.log 2>&1
+* * * * * ~/.ldm/bin/crystal-capture.sh >> ~/.ldm/logs/crystal-capture.log 2>&1
 ```
 
 The script calls `node ~/.ldm/extensions/memory-crystal/dist/cc-poller.js`. The poller fetches the OpenAI API key internally via `opRead()` (1Password SA token). No secrets in the shell script.
@@ -215,6 +215,24 @@ Provider detection in `llm.ts`:
 
 Search can be filtered by time: `--since 24h`, `--since 7d`, `--since 30d`, or an ISO date. Applied as a SQL WHERE clause before search. Available on CLI and MCP (`time_filter` parameter).
 
+### Intent Parameter
+
+`--intent <description>` disambiguates queries without adding search terms. Example: `crystal search "security" --intent "1Password"` steers toward 1Password-specific context, not repo permissions or agent secrets.
+
+Intent flows through: expansion prompt (guides LLM variations), disables strong-signal bypass, prepended to rerank query for LLM relevance scoring.
+
+### Explain Mode
+
+`--explain` shows per-result scoring breakdown: FTS (keyword) score, vector (semantic) score, RRF rank after fusion, reranker score from LLM, recency weight, final blended score. Makes search quality transparent and debuggable.
+
+### Candidate Limit
+
+`--candidates N` tunes the rerank pool size (default 40). Higher values give the LLM more results to evaluate. Lower values are faster.
+
+### LLM Cache
+
+Expansion + reranking results cached in `llm_cache` table with 7-day TTL. Same query returns instantly on second search. Cache is per-query, per-intent.
+
 ### Recency Decay
 
 Exponential decay from 1.0 to floor 0.3. Day 0: 1.0, Day 1: 0.90, Day 3: 0.74, Day 7: 0.50, Day 14+: 0.3 (floor). Fresh context wins decisively. Old content still surfaces for strong matches but doesn't bury recent results.
@@ -274,6 +292,9 @@ Memory Crystal manages `~/.ldm/` ... the universal agent home directory for [LDM
   config.json                              version, registered agents array
   bin/
     crystal-capture.sh                     cron job script (deployed by crystal init)
+  logs/
+    crystal-capture.log                    cron output (persists across reboots)
+    ldm-backup.log                         backup script output
   memory/
     crystal.db                             shared vector DB (all agents)
   extensions/
@@ -419,7 +440,9 @@ Incremental sync detects changed files via SHA-256 content hashing. Only re-embe
 
 ```bash
 # Search
-crystal search <query> [-n limit] [--agent <id>] [--since <24h|7d|30d>] [--provider <openai|ollama|google>]
+crystal search <query> [-n limit] [--agent <id>] [--since <24h|7d|30d>]
+  [--intent <description>] [--candidates N] [--explain]
+  [--provider <openai|ollama|google>]
 
 # Remember / forget
 crystal remember <text> [--category fact|preference|event|opinion|skill]
@@ -428,6 +451,11 @@ crystal forget <id>
 # Status
 crystal status [--provider <openai|ollama|google>]
 
+# MLX local LLM (Apple Silicon)
+crystal mlx setup                # auto-install Qwen2.5-3B, create LaunchAgent
+crystal mlx status               # check server health
+crystal mlx stop                 # stop the server
+
 # Source file indexing
 crystal sources add <path> --name <name>
 crystal sources sync [name]

package/_trash/RELEASE-NOTES-v0-7-28.md

@@ -1,24 +1,31 @@
 # Release Notes: memory-crystal v0.7.28
 
-**One-line summary of what this release does**
+**Move all log paths from /tmp/ to ~/.ldm/logs/ so logs survive reboots.**
 
 ## What changed
 
-Describe the changes. Not a commit list. Explain:
-- What was built or fixed
-- Why it matters
-- What the user should know
+- Cron entry for crystal-capture now logs to `~/.ldm/logs/crystal-capture.log` instead of `/tmp/ldm-dev-tools/`
+- LaunchAgent plist template for ldm-backup now logs to `~/.ldm/logs/ldm-backup.log`
+- `mkdirSync` ensures `~/.ldm/logs/` exists instead of creating `/tmp/ldm-dev-tools/`
+- CLI output shows the correct log path
 
 ## Why
 
-What problem does this solve? What was broken or missing?
+macOS clears `/tmp/` on every reboot. All cron and LaunchAgent logs were lost after restart, making it impossible to debug issues. `~/.ldm/logs/` persists across reboots and is the correct home for LDM OS logs.
 
 ## Issues closed
 
-- #91
+- wipcomputer/wip-ldm-os#120
 
 ## How to verify
 
 ```bash
-# Commands to test the changes
+# After install, check that cron entry points to ~/.ldm/logs/
+crystal init --dry-run 2>&1 | grep crystal-capture
+
+# Check backup setup points to ~/.ldm/logs/
+crystal backup setup --dry-run 2>&1 | grep ldm-backup
+
+# Verify logs land in the right place
+ls ~/.ldm/logs/
 ```

package/_trash/RELEASE-NOTES-v0-7-29.md

@@ -0,0 +1,28 @@
+# Release Notes: memory-crystal v0.7.29
+
+**Doc audit: MLX setup, deep search params, log paths, role clarification.**
+
+## What changed
+
+SKILL.md and TECHNICAL.md updated for 2 weeks of undocumented features:
+
+- **MLX local LLM:** Added as Option A in SKILL.md Step 2. CLI commands (setup, status, stop) added to TECHNICAL.md.
+- **Deep search parameters:** `--intent`, `--explain`, `--candidates` documented in both SKILL.md (crystal_search tool) and TECHNICAL.md (CLI reference + new sections for intent, explain, candidate limit, LLM cache).
+- **Log paths:** Fixed obsolete `/tmp/ldm-dev-tools/` reference to `~/.ldm/logs/`. Added logs/ to directory structure.
+- **Role clarification:** Two-role architecture (Core and Node) explicitly stated. Standalone role was removed in v0.7.22.
+
+## Why
+
+29 releases in 13 days. Docs didn't keep pace. Agents using crystal_search didn't know about --intent (query disambiguation) or --explain (scoring transparency).
+
+## Issues closed
+
+- #57
+
+## How to verify
+
+```bash
+grep "intent" SKILL.md TECHNICAL.md
+grep "mlx" SKILL.md TECHNICAL.md
+grep "ldm/logs" TECHNICAL.md
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/memory-crystal",
-  "version": "0.7.28",
+  "version": "0.7.29",
   "description": "Sovereign memory system — local-first with ephemeral encrypted relay. Your memory, your machine, your rules.",
   "repository": {
     "type": "git",