laminark 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# Laminark
+
+Persistent adaptive memory for Claude Code. Automatically captures observations from your coding sessions, classifies them using LLM-based curation, and surfaces relevant context when you need it.
+
+## Features
+
+- Automatic observation capture via Claude Code hooks (Write, Edit, Bash, etc.)
+- LLM-based classification: discoveries, problems, solutions (noise filtered out)
+- Full-text search with BM25 ranking
+- Knowledge graph with entity and relationship tracking
+- Cross-session memory scoped per project
+- Web UI for browsing observations and graph
+- Duplicate detection and secret redaction
+
+## Installation
+
+### Quick Install (Recommended)
+
+One command — no git clone needed:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/NoobyNull/Laminark/master/plugin/scripts/install.sh | bash
+```
+
+This will:
+1. Install `laminark` globally via npm
+2. Register the MCP server with Claude Code
+3. Configure hooks in `~/.claude/settings.json`
+
+### Local Installation (Development)
+
+For local development or testing:
+
+```bash
+git clone https://github.com/NoobyNull/Laminark.git
+cd Laminark
+npm install
+npm run build
+./plugin/scripts/local-install.sh
+```
+
+This uses `npm link` so changes to the repo are reflected immediately after rebuilding.
+
+### Manual Installation (Advanced)
+
+If you need manual control:
+
+```bash
+# Install the package
+npm install -g laminark
+
+# Register MCP server
+claude mcp add-json laminark '{"command":"laminark-server"}' -s user
+
+# Configure hooks manually in ~/.claude/settings.json
+# (see install.sh for the hook structure)
+```
+
+### Post-Installation
+
+Verify installation:
+
+```bash
+# If installed from repo:
+./plugin/scripts/verify-install.sh
+
+# Or check manually:
+npm list -g laminark && claude mcp list | grep laminark
+```
+
+Laminark will now run in every Claude Code session. Each project's memory is isolated by directory path -- Project A and Project B never share data, but each project remembers across sessions.
+
+### Updating
+
+```bash
+npm update -g laminark
+# Or: ./plugin/scripts/update.sh
+```
+
+### Uninstalling
+
+```bash
+claude mcp remove laminark -s user
+npm uninstall -g laminark
+# Then remove laminark hook entries from ~/.claude/settings.json
+# Optionally: rm -rf ~/.laminark  (deletes all memories)
+```
+
+## Recommended: GSD (Get Shit Done)
+
+Laminark pairs well with [GSD](https://github.com/gsd-framework/gsd) by [@gsd-framework](https://github.com/gsd-framework), a structured workflow plugin for Claude Code. While Laminark handles persistent memory and context, GSD provides project planning, phased execution, and atomic commits. Together they give Claude Code sessions continuity (Laminark) and structure (GSD).
+
+> **Note:** GSD is an independent project. Its authors do not endorse or recommend Laminark. This is our recommendation based on how well the two tools complement each other.
+
+```bash
+claude plugin add gsd
+```
+
+The install scripts will offer to install GSD automatically if it isn't already present.
+
+## Why User-Level?
+
+- Works in every project automatically -- no per-project `.mcp.json` needed
+- Cross-session memory persists for each project
+- Single database at `~/.laminark/data.db`, scoped by project hash
+- Hooks and MCP tools are available everywhere
+
+## Data Storage
+
+All data is stored in a single SQLite database at `~/.laminark/data.db`. Each project is identified by a SHA-256 hash of its directory path, ensuring complete isolation between projects.
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `save_memory` | Save an observation with optional title |
+| `recall` | Search, view, purge, or restore memories |
+| `query_graph` | Query the knowledge graph for entities and relationships |
+| `graph_stats` | View knowledge graph statistics |
+| `topic_context` | Show recently stashed context threads |
+| `status` | Show Laminark status and statistics |
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## Release History
+
+See [CHANGELOG.md](CHANGELOG.md) for detailed release notes.
+
+**Versioning:** Laminark uses `MILESTONE.PHASE.SEQUENTIAL` format (e.g., v2.21.0) aligned with GSD workflow phases.
+
+**Latest Releases:**
+- **v2.21.0** (2026-02-14) - Phase 21: Graph Visualization (Milestone v2.2 complete)
+- **v2.18.0** (2026-02-14) - Phase 18: Agent SDK Migration (Milestone v2.1 complete)
+- **v2.16.0** (2026-02-10) - Phase 16: Staleness Management (Milestone v2.0 complete)
+- **v1.8.0** (2026-02-09) - Phase 8: Web Visualization (Milestone v1.0 complete)
+
+See [.planning/MILESTONES.md](.planning/MILESTONES.md) for comprehensive milestone documentation.
+
+## License
+
+ISC

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "laminark",
+  "version": "0.1.0",
+  "description": "Persistent adaptive memory for Claude Code",
+  "type": "module",
+  "bin": {
+    "laminark-server": "./plugin/dist/index.js",
+    "laminark-hook": "./plugin/dist/hooks/handler.js"
+  },
+  "main": "./plugin/dist/index.js",
+  "types": "./plugin/dist/index.d.ts",
+  "files": [
+    "plugin"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build",
+    "install:local": "./plugin/scripts/local-install.sh",
+    "install:global": "./plugin/scripts/install.sh",
+    "update": "./plugin/scripts/update.sh",
+    "uninstall": "./plugin/scripts/uninstall.sh",
+    "verify": "./plugin/scripts/verify-install.sh",
+    "sync": "./plugin/scripts/dev-sync.sh",
+    "dev": "npm run build && npm run sync"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NoobyNull/Laminark.git"
+  },
+  "keywords": [
+    "claude",
+    "memory",
+    "mcp",
+    "sqlite"
+  ],
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/NoobyNull/Laminark/issues"
+  },
+  "homepage": "https://github.com/NoobyNull/Laminark#readme",
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.42",
+    "@hono/node-server": "^1.19.9",
+    "@huggingface/transformers": "^3.8.1",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "better-sqlite3": "^12.6.2",
+    "hono": "^4.11.9",
+    "sqlite-vec": "^0.1.7-alpha.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.2.2",
+    "tsdown": "^0.20.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "laminark",
+  "description": "Persistent adaptive memory for Claude Code. Automatic observation capture, semantic search, topic detection, knowledge graph, and web visualization.",
+  "version": "0.1.0",
+  "author": {
+    "name": "NoobyNull"
+  },
+  "homepage": "https://github.com/NoobyNull/Laminark",
+  "repository": "https://github.com/NoobyNull/Laminark",
+  "license": "ISC",
+  "keywords": ["memory", "mcp", "sqlite", "knowledge-graph", "semantic-search"],
+  "skills": "./skills/"
+}

package/plugin/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "laminark": {
+      "command": "bash",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/scripts/ensure-deps.sh",
+        "node",
+        "${CLAUDE_PLUGIN_ROOT}/dist/index.js"
+      ]
+    }
+  }
+}

package/plugin/CLAUDE.md

@@ -0,0 +1,10 @@
+# Memory & Context
+
+When you need to recall prior work, decisions, or context:
+- **First** query Laminark's memory tools (`recall`, `query_graph`, `query_branches`) before resorting to grep/glob searches
+- Use `recall` with keyword searches to find past observations, decisions, and findings
+- Use `query_graph` to find relationships between files, decisions, and problems
+- Use `query_branches` to see work history - what was investigated, fixed, built, and where it left off
+- Use `show_branch` to trace the full arc of a specific work unit (investigation -> diagnosis -> planning -> execution -> verification)
+- Use `save_memory` to persist important decisions, findings, and reference material
+- Only fall back to raw file searches (Grep, Glob) when Laminark has no relevant results

package/plugin/commands/recall.md

@@ -0,0 +1,55 @@
+# /laminark:recall
+
+Search Laminark memories by description or topic.
+
+## Usage
+
+/laminark:recall {description of what you're looking for}
+
+## Instructions
+
+When the user invokes this command:
+
+1. Take the text provided after the command as the search query
+2. Call the `search` MCP tool with:
+   - `query`: The user's search description
+   - `limit`: 10 (show top 10 results)
+3. Present the results to the user in a readable format:
+   - Show each result with its relevance score, a content snippet, the source, and when it was created
+   - Group results by relevance tier if helpful (highly relevant, somewhat relevant)
+   - If results include memories from different sessions, note which session they came from
+
+## Response Format
+
+Present results like this:
+
+**Memory Search: "{query}"**
+
+Found {N} relevant memories:
+
+1. **[{score}% match]** {content snippet, first 200 chars}
+   _{source} | {relative time}_
+
+2. **[{score}% match]** {content snippet}
+   _{source} | {relative time}_
+
+...
+
+_Use the search tool for more specific queries, or get_observations for full details on any memory._
+
+## Examples
+
+User: /laminark:recall authentication decisions
+Action: Call search with query="authentication decisions"
+Response: Show top results about auth-related memories with scores and snippets
+
+User: /laminark:recall what database did we choose
+Action: Call search with query="what database did we choose"
+Response: Show results mentioning database selection decisions
+
+## Notes
+
+- Results use hybrid search (keyword + semantic) for best matching
+- If no results are found, suggest the user try different search terms or check if they have saved any memories yet
+- If no query is provided after the command, ask the user what they'd like to search for
+- For detailed view of any result, Claude can use the get_observations MCP tool with the observation ID

package/plugin/commands/remember.md

@@ -0,0 +1,34 @@
+# /laminark:remember
+
+Save a memory to Laminark for future retrieval.
+
+## Usage
+
+/laminark:remember {text to remember}
+
+## Instructions
+
+When the user invokes this command:
+
+1. Take the text provided after the command as the memory content
+2. Call the `save_memory` MCP tool with:
+   - `content`: The user's text exactly as provided
+   - `source`: "slash:remember" (identifies this as an explicit user save)
+3. Confirm to the user that the memory has been saved
+4. Show a brief snippet of what was saved (first 100 characters)
+
+## Examples
+
+User: /laminark:remember The auth system uses JWT with 15-minute expiry and refresh tokens stored in httpOnly cookies
+Action: Call save_memory with content="The auth system uses JWT with 15-minute expiry and refresh tokens stored in httpOnly cookies" and source="slash:remember"
+Response: "Saved to memory: 'The auth system uses JWT with 15-minute expiry and refresh tokens stored in httpOnly cookies'"
+
+User: /laminark:remember We decided to use Postgres instead of MySQL for the new service because of JSONB support
+Action: Call save_memory with the full text
+Response: "Saved to memory: 'We decided to use Postgres instead of MySQL for the new serv...'"
+
+## Notes
+
+- Memories saved via /laminark:remember are high-priority in search results (source: "slash:remember")
+- These memories persist across sessions and are included in session context injection
+- If no text is provided after the command, ask the user what they'd like to remember

package/plugin/commands/resume.md

@@ -0,0 +1,45 @@
+# /laminark:resume
+
+Resume a previously stashed context thread, or list all available stashed threads.
+
+## Usage
+
+/laminark:resume
+/laminark:resume {stash-id}
+
+## Instructions
+
+When the user invokes this command:
+
+### List mode (no ID provided)
+
+1. Call the `topic_context` MCP tool with no arguments (or limit: 5)
+2. Present the stashed threads as a numbered list showing:
+   - Topic label
+   - How long ago it was stashed
+   - Brief summary (first 80 characters)
+3. Tell the user they can resume a specific thread by providing its ID
+
+### Resume mode (ID provided)
+
+1. Call the `topic_context` MCP tool to look up the stash
+2. Restore the context from the stash observations into the conversation
+3. Confirm to the user which thread was resumed and how many observations were restored
+4. Summarize the key context from the restored thread so the user can pick up where they left off
+
+## Examples
+
+User: /laminark:resume
+Action: Call topic_context to list stashed threads
+Response: Show numbered list of available threads with topic labels and timestamps
+
+User: /laminark:resume abc123def456
+Action: Resume the specific stash, inject its context
+Response: "Resumed: 'JWT authentication' -- Context restored with 5 observations. Here's where you left off: ..."
+
+## Notes
+
+- Only threads with status "stashed" are shown (already resumed threads are excluded)
+- Resuming a thread marks it as "resumed" so it no longer appears in the list
+- The restored context includes observation snapshots from the time of stashing
+- If no stashed threads exist, inform the user they are working in a single thread

package/plugin/commands/stash.md

@@ -0,0 +1,34 @@
+# /laminark:stash
+
+Manually stash the current session's context for later retrieval.
+
+## Usage
+
+/laminark:stash [optional label]
+
+## Instructions
+
+When the user invokes this command:
+
+1. Call the `save_memory` MCP tool to persist current observations, then call the stash handler to snapshot the current session
+2. If a label is provided after the command, use it as the stash topic label
+3. If no label is provided, one is generated automatically from the earliest observation
+4. Confirm to the user that their context was stashed
+5. Show the topic label and remind them about /laminark:resume
+
+## Examples
+
+User: /laminark:stash authentication implementation
+Action: Stash current session context with label "authentication implementation"
+Response: "Context stashed: 'authentication implementation'. Use /laminark:resume to return to it."
+
+User: /laminark:stash
+Action: Stash current session context with auto-generated label
+Response: "Context stashed: 'Initial project setup and configur...'. Use /laminark:resume to return to it."
+
+## Notes
+
+- Stashing preserves a snapshot of the current session's observations
+- The stash remains available across sessions until resumed or deleted
+- Use /laminark:resume to list available stashes or restore a specific one
+- Automatic stashing also occurs when topic shifts are detected during normal work

package/plugin/commands/status.md

@@ -0,0 +1,33 @@
+# /laminark:status
+
+Show Laminark system status: connection info, memory count, token estimates, and capabilities.
+
+## Usage
+
+/laminark:status
+
+## Instructions
+
+When the user invokes this command:
+
+1. Call the `status` MCP tool with no arguments
+2. Present the returned dashboard directly to the user
+
+The tool returns a formatted status report including:
+- **Connection**: project path, project hash, database path, uptime
+- **Capabilities**: vector search availability, embedding worker status
+- **Memories**: observation count, embedded count, session count, stashed threads
+- **Tokens**: estimated total tokens across all stored memories
+- **Knowledge Graph**: node and edge counts
+
+## Examples
+
+User: /laminark:status
+Action: Call the status MCP tool
+Response: Display the formatted status dashboard
+
+## Notes
+
+- This is a read-only diagnostic command with no side effects
+- Token estimates use the ~4 chars/token heuristic
+- Uptime reflects time since the MCP server process started

package/plugin/dist/analysis/worker.d.ts

@@ -0,0 +1 @@
+export { };

package/plugin/dist/analysis/worker.js

@@ -0,0 +1,233 @@
+import { t as getConfigDir } from "../config-t8LZeB-u.mjs";
+import { join } from "node:path";
+import { parentPort } from "node:worker_threads";
+
+//#region src/analysis/engines/local-onnx.ts
+/**
+* Local ONNX embedding engine using @huggingface/transformers.
+*
+* Loads BGE Small EN v1.5 (quantized q8) via dynamic import() for
+* zero startup cost (DQ-04). Model files are cached in ~/.laminark/models/.
+*/
+/**
+* Embedding engine backed by BGE Small EN v1.5 running locally via ONNX Runtime.
+*
+* All public methods catch errors internally and return null/false.
+*/
+var LocalOnnxEngine = class {
+	pipe = null;
+	ready = false;
+	/**
+	* Lazily loads the model via dynamic import().
+	*
+	* - Uses `@huggingface/transformers` loaded at runtime (not bundled)
+	* - Caches model files in ~/.laminark/models/
+	* - Returns false on any error (missing runtime, download failure, etc.)
+	*/
+	async initialize() {
+		try {
+			const { pipeline, env } = await import("@huggingface/transformers");
+			env.cacheDir = join(getConfigDir(), "models");
+			this.pipe = await pipeline("feature-extraction", "Xenova/bge-small-en-v1.5", { dtype: "q8" });
+			this.ready = true;
+			return true;
+		} catch {
+			this.ready = false;
+			return false;
+		}
+	}
+	/**
+	* Embeds a single text string into a 384-dimensional vector.
+	*
+	* Returns null if:
+	* - Engine not initialized
+	* - Input is empty/whitespace
+	* - Pipeline throws
+	*/
+	async embed(text) {
+		if (!this.ready || !this.pipe) return null;
+		if (!text || text.trim().length === 0) return null;
+		try {
+			const output = await this.pipe(text, {
+				pooling: "cls",
+				normalize: true
+			});
+			return Float32Array.from(output.data);
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Embeds multiple texts, preserving order.
+	*
+	* Returns null for any text that was empty or failed.
+	*/
+	async embedBatch(texts) {
+		const results = [];
+		for (const text of texts) if (!text || text.trim().length === 0) results.push(null);
+		else results.push(await this.embed(text));
+		return results;
+	}
+	/** BGE Small EN v1.5 produces 384-dimensional embeddings. */
+	dimensions() {
+		return 384;
+	}
+	/** Engine identifier. */
+	name() {
+		return "bge-small-en-v1.5-q8";
+	}
+	/** Whether the model loaded successfully. */
+	isReady() {
+		return this.ready;
+	}
+};
+
+//#endregion
+//#region src/analysis/engines/keyword-only.ts
+/**
+* Embedding engine that produces no embeddings.
+*
+* Acts as a silent fallback so that the rest of the system can
+* operate in keyword-only mode without special-casing missing engines.
+*/
+var KeywordOnlyEngine = class {
+	/** Always returns null -- no model available. */
+	async embed() {
+		return null;
+	}
+	/** Returns array of nulls matching input length. */
+	async embedBatch(texts) {
+		return texts.map(() => null);
+	}
+	/** No dimensions -- no model. */
+	dimensions() {
+		return 0;
+	}
+	/** Engine identifier. */
+	name() {
+		return "keyword-only";
+	}
+	/** Intentionally returns false -- this engine has no model. */
+	async initialize() {
+		return false;
+	}
+	/** Always false -- no model loaded. */
+	isReady() {
+		return false;
+	}
+};
+
+//#endregion
+//#region src/analysis/embedder.ts
+/**
+* EmbeddingEngine interface and factory.
+*
+* Defines the pluggable abstraction for text embedding.
+* All consumers depend on this interface -- never on concrete engines.
+*/
+/**
+* Creates and initializes an embedding engine.
+*
+* Attempts LocalOnnxEngine first. If initialization fails (missing model,
+* ONNX runtime unavailable, etc.), falls back to KeywordOnlyEngine.
+*
+* Never throws -- always returns a valid engine.
+*/
+async function createEmbeddingEngine() {
+	const onnxEngine = new LocalOnnxEngine();
+	if (await onnxEngine.initialize()) return onnxEngine;
+	return new KeywordOnlyEngine();
+}
+
+//#endregion
+//#region src/analysis/worker.ts
+/**
+* Worker thread entry point for off-main-thread embedding.
+*
+* Receives embed/embed_batch/shutdown messages from the main thread via
+* parentPort, runs the embedding engine, and responds with Float32Array
+* results using zero-copy transfer.
+*
+* Compiled as a separate tsdown entry point to dist/analysis/worker.js.
+*/
+if (!parentPort) throw new Error("worker.ts must be run as a Worker thread");
+const port = parentPort;
+async function init() {
+	let engineName = "keyword-only";
+	let dimensions = 0;
+	try {
+		const engine = await createEmbeddingEngine();
+		engineName = engine.name();
+		dimensions = engine.dimensions();
+		port.postMessage({
+			type: "ready",
+			engineName,
+			dimensions
+		});
+		port.on("message", async (msg) => {
+			if (msg.type === "embed") try {
+				const embedding = await engine.embed(msg.text);
+				if (embedding === null) port.postMessage({
+					type: "embed_result",
+					id: msg.id,
+					embedding: null
+				});
+				else {
+					const buf = embedding.buffer;
+					port.postMessage({
+						type: "embed_result",
+						id: msg.id,
+						embedding
+					}, [buf]);
+				}
+			} catch {
+				port.postMessage({
+					type: "embed_result",
+					id: msg.id,
+					embedding: null
+				});
+			}
+			else if (msg.type === "embed_batch") try {
+				const embeddings = await engine.embedBatch(msg.texts);
+				const transferList = [];
+				for (const emb of embeddings) if (emb !== null) transferList.push(emb.buffer);
+				port.postMessage({
+					type: "embed_batch_result",
+					id: msg.id,
+					embeddings
+				}, transferList);
+			} catch {
+				port.postMessage({
+					type: "embed_batch_result",
+					id: msg.id,
+					embeddings: msg.texts.map(() => null)
+				});
+			}
+			else if (msg.type === "shutdown") process.exit(0);
+		});
+	} catch {
+		port.postMessage({
+			type: "ready",
+			engineName,
+			dimensions
+		});
+		port.on("message", (msg) => {
+			if (msg.type === "embed") port.postMessage({
+				type: "embed_result",
+				id: msg.id,
+				embedding: null
+			});
+			else if (msg.type === "embed_batch") port.postMessage({
+				type: "embed_batch_result",
+				id: msg.id,
+				embeddings: msg.texts.map(() => null)
+			});
+			else if (msg.type === "shutdown") process.exit(0);
+		});
+	}
+}
+init();
+
+//#endregion
+export {  };
+//# sourceMappingURL=worker.js.map