decisionnode 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 DecisionNode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# DecisionNode
+
+> Structured, queryable memory for development decisions. Stores architectural choices as vector embeddings, exposes them to AI agents via MCP.
+
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![npm](https://img.shields.io/npm/v/decisionnode.svg)
+
+---
+
+Your AI keeps forgetting what you agreed on. You say "use Tailwind, no CSS modules" — next session, it writes CSS modules. DecisionNode stores these decisions as vector embeddings so the AI can search them before writing code.
+
+Not a markdown file. A queryable memory layer with semantic search.
+
+## Install
+
+```bash
+npm install -g decisionnode
+cd your-project
+decide init      # creates project store + .mcp.json for AI clients
+decide setup     # configure Gemini API key (free tier)
+```
+
+`decide init` creates a `.mcp.json` in your project — AI clients like Claude Code and Cursor connect automatically.
+
+## How it works
+
+1. **A decision is made** — via `decide add` or the AI calls `add_decision` through MCP
+2. **Embedded as a vector** — using Gemini's `gemini-embedding-001`, stored locally in `vectors.json`
+3. **AI retrieves it later** — calls `search_decisions` via MCP, gets back relevant decisions ranked by cosine similarity
+
+The retrieval is explicit — the AI calls the MCP tool to search. Decisions are not injected into a system prompt.
+
+## Two interfaces
+
+| | CLI (`decide`) | MCP Server (`decide-mcp`) |
+|---|---|---|
+| **For** | You | Your AI |
+| **How** | Terminal commands | Structured JSON over MCP |
+| **Does** | Setup, add, search, edit, deprecate, export, import, config | Search, add, update, delete, list, history |
+
+Both read and write to the same local store (`~/.decisionnode/`).
+
+## Quick reference
+
+```bash
+decide add                          # interactive add
+decide add -s UI -d "Use Tailwind"  # one-command add
+decide add --global                 # applies to all projects
+decide search "error handling"      # semantic search
+decide list                         # list all (includes global)
+decide deprecate ui-003             # soft-delete (reversible)
+decide activate ui-003              # bring it back
+decide check                        # embedding health
+decide embed                        # fix missing embeddings
+decide export json > decisions.json # export to file
+```
+
+## Documentation
+
+Full docs at [decisionnode.dev/docs](https://decisionnode.dev/docs)
+
+- [Quickstart](https://decisionnode.dev/docs/quickstart)
+- [CLI Reference](https://decisionnode.dev/docs/cli) — all commands
+- [MCP Server](https://decisionnode.dev/docs/mcp) — 9 tools, setup for Claude/Cursor/Windsurf
+- [Decision Nodes](https://decisionnode.dev/docs/decisions) — structure, fields, lifecycle
+- [Context Engine](https://decisionnode.dev/docs/context) — embedding, search, conflict detection
+- [Configuration](https://decisionnode.dev/docs/setup) — storage, search sensitivity, global decisions
+- [Workflows](https://decisionnode.dev/docs/workflows) — common patterns
+
+For LLM consumption: [decisionnode.dev/decisionnode-docs.md](https://decisionnode.dev/decisionnode-docs.md)
+
+## Contributing
+
+The CLI and MCP server are just the start. There's a VS Code extension, a marketplace for shared decision packs, and cloud sync being worked on — contributions to any of these are welcome.
+
+Whether it's a bug fix, a new feature, improving the docs, or just starring the repo — all help is appreciated. See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get started.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/ai/gemini.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Get embedding for text.
+ * Priority:
+ * 1. Pro subscriber -> Cloud embedding (server-side)
+ * 2. Local API key -> Local embedding
+ * 3. None -> Error
+ *
+ * @param text - Text to embed
+ * @param projectName - Optional project name for cloud context
+ */
+export declare function getEmbedding(text: string, projectName?: string): Promise<number[]>;
+/**
+ * Check if embedding is available (either local or cloud)
+ */
+export declare function isEmbeddingAvailable(): Promise<boolean>;

package/dist/ai/gemini.js

@@ -0,0 +1,56 @@
+import { GoogleGenerativeAI } from '@google/generative-ai';
+import { getCloudEmbedding, isProSubscriber } from '../cloud.js';
+// Get API key from environment (set by parent process or .env file)
+const apiKey = process.env.GEMINI_API_KEY;
+// We don't throw yet because the user might just be listing decisions
+// We'll check again when they try to use an AI feature
+const genAI = apiKey ? new GoogleGenerativeAI(apiKey) : null;
+const model = genAI ? genAI.getGenerativeModel({ model: "gemini-embedding-001" }) : null;
+/**
+ * Get embedding for text.
+ * Priority:
+ * 1. Pro subscriber -> Cloud embedding (server-side)
+ * 2. Local API key -> Local embedding
+ * 3. None -> Error
+ *
+ * @param text - Text to embed
+ * @param projectName - Optional project name for cloud context
+ */
+export async function getEmbedding(text, projectName) {
+    // 1. Check if user is Pro - use cloud embedding
+    // This allows Pro users to use the tool with ZERO config (no local API key)
+    try {
+        const isPro = await isProSubscriber();
+        if (isPro) {
+            const cloudEmbedding = await getCloudEmbedding(text, projectName);
+            if (cloudEmbedding) {
+                return cloudEmbedding;
+            }
+            // If cloud fails (e.g. network error), fall back to local if available
+        }
+    }
+    catch {
+        // Build/env error, ignore and try local
+    }
+    // 2. If local API key is available, use it
+    if (model) {
+        try {
+            const result = await model.embedContent(text);
+            return result.embedding.values;
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    // 3. No key available
+    throw new Error("No Gemini API key configured.\n" +
+        "Run: decide setup");
+}
+/**
+ * Check if embedding is available (either local or cloud)
+ */
+export async function isEmbeddingAvailable() {
+    if (model)
+        return true;
+    return await isProSubscriber();
+}

package/dist/ai/rag.d.ts

@@ -0,0 +1,79 @@
+import { DecisionNode } from '../types.js';
+interface VectorEntry {
+    vector: number[];
+    embeddedAt: string;
+}
+type VectorCache = Record<string, VectorEntry | number[]>;
+interface ScoredDecision {
+    decision: DecisionNode;
+    score: number;
+}
+/**
+ * Load the vector cache from disk
+ */
+export declare function loadVectorCache(): Promise<VectorCache>;
+/**
+ * Save the vector cache to disk
+ */
+export declare function saveVectorCache(cache: VectorCache): Promise<void>;
+/**
+ * Load the global vector cache from disk
+ */
+export declare function loadGlobalVectorCache(): Promise<VectorCache>;
+/**
+ * Save the global vector cache to disk
+ */
+export declare function saveGlobalVectorCache(cache: VectorCache): Promise<void>;
+/**
+ * Embed a single global decision
+ * Throws on failure so callers can report embedding status.
+ */
+export declare function embedGlobalDecision(decision: DecisionNode): Promise<void>;
+/**
+ * Clear the embedding for a deleted global decision
+ */
+export declare function clearGlobalEmbedding(decisionId: string): Promise<void>;
+/**
+ * Embed a single decision immediately.
+ * Called automatically when decisions are added or updated.
+ * Throws on failure so callers can report embedding status.
+ */
+export declare function embedDecision(decision: DecisionNode): Promise<void>;
+/**
+ * Clear the embedding for a deleted decision
+ */
+export declare function clearEmbedding(decisionId: string): Promise<void>;
+/**
+ * Update embedding for a renamed decision ID
+ */
+export declare function renameEmbedding(oldId: string, newId: string): Promise<void>;
+/**
+ * Batch embed multiple decisions (used for import)
+ */
+export declare function embedDecisions(decisions: DecisionNode[]): Promise<{
+    success: number;
+    failed: number;
+}>;
+/**
+ * Find the most relevant decisions for a given query
+ * Automatically includes global decisions in results
+ */
+export declare function findRelevantDecisions(query: string, limit?: number): Promise<ScoredDecision[]>;
+/**
+ * Get decisions that are missing embeddings
+ */
+export declare function getUnembeddedDecisions(): Promise<DecisionNode[]>;
+/**
+ * Embed all unembedded decisions
+ * Returns list of embedded decision IDs
+ */
+export declare function embedAllDecisions(): Promise<{
+    embedded: string[];
+    failed: string[];
+}>;
+/**
+ * Find potential conflicts with existing decisions
+ * Uses semantic similarity to find decisions that might contradict a new one
+ */
+export declare function findPotentialConflicts(newDecisionText: string, threshold?: number): Promise<ScoredDecision[]>;
+export {};

package/dist/ai/rag.js

@@ -0,0 +1,268 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { listDecisions, listGlobalDecisions } from '../store.js';
+import { getEmbedding } from './gemini.js';
+import { getProjectRoot, ensureProjectFolder, getGlobalDecisionsPath, ensureGlobalFolder } from '../env.js';
+// getProjectRoot() returns ~/.decisionnode/.decisions/{projectname}/
+const VECTORS_FILE = () => path.join(getProjectRoot(), 'vectors.json');
+/**
+ * Load the vector cache from disk
+ */
+export async function loadVectorCache() {
+    try {
+        const content = await fs.readFile(VECTORS_FILE(), 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Save the vector cache to disk
+ */
+export async function saveVectorCache(cache) {
+    ensureProjectFolder();
+    await fs.writeFile(VECTORS_FILE(), JSON.stringify(cache, null, 2), 'utf-8');
+}
+/**
+ * Get the vector from a cache entry (handles both legacy and new format)
+ */
+function getVectorFromEntry(entry) {
+    if (Array.isArray(entry))
+        return entry;
+    return entry.vector;
+}
+// Global vectors file path
+const GLOBAL_VECTORS_FILE = () => path.join(getGlobalDecisionsPath(), 'vectors.json');
+/**
+ * Load the global vector cache from disk
+ */
+export async function loadGlobalVectorCache() {
+    try {
+        const content = await fs.readFile(GLOBAL_VECTORS_FILE(), 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Save the global vector cache to disk
+ */
+export async function saveGlobalVectorCache(cache) {
+    ensureGlobalFolder();
+    await fs.writeFile(GLOBAL_VECTORS_FILE(), JSON.stringify(cache, null, 2), 'utf-8');
+}
+/**
+ * Embed a single global decision
+ * Throws on failure so callers can report embedding status.
+ */
+export async function embedGlobalDecision(decision) {
+    const cache = await loadGlobalVectorCache();
+    const text = getDecisionText(decision);
+    const embedding = await getEmbedding(text);
+    cache[decision.id] = {
+        vector: embedding,
+        embeddedAt: new Date().toISOString()
+    };
+    await saveGlobalVectorCache(cache);
+}
+/**
+ * Clear the embedding for a deleted global decision
+ */
+export async function clearGlobalEmbedding(decisionId) {
+    try {
+        const cache = await loadGlobalVectorCache();
+        delete cache[decisionId];
+        await saveGlobalVectorCache(cache);
+    }
+    catch {
+        // Silently fail
+    }
+}
+/**
+ * Generate the text representation of a decision for embedding
+ */
+function getDecisionText(decision) {
+    return `${decision.scope}: ${decision.decision}. ${decision.rationale || ''} ${decision.constraints?.join(' ') || ''}`;
+}
+/**
+ * Calculate Cosine Similarity between two vectors
+ */
+function cosineSimilarity(vecA, vecB) {
+    const dotProduct = vecA.reduce((acc, val, i) => acc + val * vecB[i], 0);
+    const magnitudeA = Math.sqrt(vecA.reduce((acc, val) => acc + val * val, 0));
+    const magnitudeB = Math.sqrt(vecB.reduce((acc, val) => acc + val * val, 0));
+    return dotProduct / (magnitudeA * magnitudeB);
+}
+/**
+ * Embed a single decision immediately.
+ * Called automatically when decisions are added or updated.
+ * Throws on failure so callers can report embedding status.
+ */
+export async function embedDecision(decision) {
+    const cache = await loadVectorCache();
+    const text = getDecisionText(decision);
+    const embedding = await getEmbedding(text);
+    cache[decision.id] = {
+        vector: embedding,
+        embeddedAt: new Date().toISOString()
+    };
+    await saveVectorCache(cache);
+}
+/**
+ * Clear the embedding for a deleted decision
+ */
+export async function clearEmbedding(decisionId) {
+    try {
+        const cache = await loadVectorCache();
+        delete cache[decisionId];
+        await saveVectorCache(cache);
+    }
+    catch {
+        // Silently fail
+    }
+}
+/**
+ * Update embedding for a renamed decision ID
+ */
+export async function renameEmbedding(oldId, newId) {
+    try {
+        const cache = await loadVectorCache();
+        if (cache[oldId]) {
+            cache[newId] = cache[oldId];
+            delete cache[oldId];
+            await saveVectorCache(cache);
+        }
+    }
+    catch {
+        // Silently fail
+    }
+}
+/**
+ * Batch embed multiple decisions (used for import)
+ */
+export async function embedDecisions(decisions) {
+    const cache = await loadVectorCache();
+    let success = 0;
+    let failed = 0;
+    for (const decision of decisions) {
+        try {
+            // Rate limit protection
+            await new Promise(r => setTimeout(r, 500));
+            const text = getDecisionText(decision);
+            const embedding = await getEmbedding(text);
+            cache[decision.id] = {
+                vector: embedding,
+                embeddedAt: new Date().toISOString()
+            };
+            success++;
+        }
+        catch {
+            failed++;
+        }
+    }
+    await saveVectorCache(cache);
+    return { success, failed };
+}
+/**
+ * Find the most relevant decisions for a given query
+ * Automatically includes global decisions in results
+ */
+export async function findRelevantDecisions(query, limit = 3) {
+    const cache = await loadVectorCache();
+    const globalCache = await loadGlobalVectorCache();
+    const queryEmbedding = await getEmbedding(query);
+    // Project decisions
+    const allDecisions = await listDecisions();
+    const activeDecisions = allDecisions.filter(d => d.status === 'active');
+    // Global decisions (already prefixed with "global:")
+    const globalDecisions = await listGlobalDecisions();
+    const activeGlobalDecisions = globalDecisions.filter(d => d.status === 'active');
+    const scores = [];
+    // Score project decisions
+    for (const decision of activeDecisions) {
+        if (cache[decision.id]) {
+            const score = cosineSimilarity(queryEmbedding, getVectorFromEntry(cache[decision.id]));
+            scores.push({ decision, score });
+        }
+    }
+    // Score global decisions (stored without prefix in cache)
+    for (const decision of activeGlobalDecisions) {
+        const rawId = decision.id.replace(/^global:/, '');
+        if (globalCache[rawId]) {
+            const score = cosineSimilarity(queryEmbedding, getVectorFromEntry(globalCache[rawId]));
+            scores.push({ decision, score });
+        }
+    }
+    return scores
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+}
+/**
+ * Get decisions that are missing embeddings
+ */
+export async function getUnembeddedDecisions() {
+    const cache = await loadVectorCache();
+    const allDecisions = await listDecisions();
+    return allDecisions.filter(d => !cache[d.id]);
+}
+/**
+ * Embed all unembedded decisions
+ * Returns list of embedded decision IDs
+ */
+export async function embedAllDecisions() {
+    const unembedded = await getUnembeddedDecisions();
+    const embedded = [];
+    const failed = [];
+    if (unembedded.length === 0) {
+        return { embedded, failed };
+    }
+    const cache = await loadVectorCache();
+    for (const decision of unembedded) {
+        try {
+            await new Promise(r => setTimeout(r, 500));
+            const text = getDecisionText(decision);
+            const embedding = await getEmbedding(text);
+            cache[decision.id] = {
+                vector: embedding,
+                embeddedAt: new Date().toISOString()
+            };
+            embedded.push(decision.id);
+        }
+        catch {
+            failed.push(decision.id);
+        }
+    }
+    if (embedded.length > 0) {
+        await saveVectorCache(cache);
+    }
+    return { embedded, failed };
+}
+/**
+ * Find potential conflicts with existing decisions
+ * Uses semantic similarity to find decisions that might contradict a new one
+ */
+export async function findPotentialConflicts(newDecisionText, threshold = 0.75) {
+    try {
+        const cache = await loadVectorCache();
+        if (Object.keys(cache).length === 0)
+            return [];
+        const newEmbedding = await getEmbedding(newDecisionText);
+        const allDecisions = await listDecisions();
+        const activeDecisions = allDecisions.filter(d => d.status === 'active');
+        const conflicts = [];
+        for (const decision of activeDecisions) {
+            if (cache[decision.id]) {
+                const score = cosineSimilarity(newEmbedding, getVectorFromEntry(cache[decision.id]));
+                if (score >= threshold) {
+                    conflicts.push({ decision, score });
+                }
+            }
+        }
+        return conflicts.sort((a, b) => b.score - a.score);
+    }
+    catch {
+        return []; // API key not set or other error
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};