memgrid 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+All notable changes to MemGrid.
+
+## v0.5.0 — Multi-Language + Incremental Sync (2026-06-28)
+
+### Added — Language-Agnostic Scanner Architecture
+- `Scanner` interface: `name`, `scan()`, `scanFiles?()`, `detect()`
+- `CompositeScanner`: auto-detects and composes multiple language scanners
+- **TypeScript** — `ts-morph` AST (classes, methods, exported functions, call graph associations)
+- **JavaScript** — regex (exported functions, classes, arrow functions)
+- **Python** — regex (functions, classes, decorators, docstrings)
+- **Go** — regex (functions, methods, structs, interfaces)
+- **Rust** — regex (functions, structs, enums, traits, impl blocks)
+- **Markdown** — headings as knowledge units from any `.md` file
+- **Rules** — `.claude/rules/*.md` → pattern + trigger units (universal, extracted from TS scanner)
+- **Config** — `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `docker-compose.yml` (universal)
+
+### Added — Incremental Sync
+- `memgrid sync` CLI command for incremental re-scan after code changes
+- `mg.sync()` API: hash-based file diff against baseline snapshot
+- File snapshots stored in `mesh.json.fileSnapshot` (SHA-256 per scanned file)
+- Fuzzy match repair: Jaccard + Dice similarity for fixing broken associations
+- Stale detection: marks orphaned units when source files are deleted
+- Fast path: 0 changes detected in ~5ms (hash compare only)
+
+### Changed
+- `mg.init()` now records initial file snapshot for future syncs
+- `MemoryGrid` type extended with optional `fileSnapshot`
+
+### Performance
+| Scenario | Time |
+|----------|------|
+| Sync 0 changes | ~5ms |
+| Sync 1 file | ~2s |
+| Sync 5 files (typical PR) | ~2-3s |
+| Full init (150 units) | ~10s |
+
+## v0.4.0 — Hybrid Semantic Search (2026-06-27)
+
+### Added
+- Hybrid search: combines MiniSearch (keyword) with semantic similarity
+- Configurable `semanticWeight` (0.0 = pure keyword, 1.0 = pure semantic)
+- Keyword embedding provider built-in (no external API required)
+- `--semantic` flag on CLI search command
+
+### Performance
+- 10 searches: 670ms → 3ms (223x improvement)
+- Repeated queries: 0ms (LRU cache)
+- Disk reload: 45ms → 5ms (9x, switched from YAML to JSON)
+
+## v0.3.0 — Auto-Learning Engine (2026-06-27)
+
+### Added
+- Post-task analysis: `mg.analyzeTask()` detects new methods, patterns, errors, decisions
+- `mg.applySuggestions()` writes learning results back to grid
+- `mg.formatSuggestions()` renders diff for human review
+- Learning suggestion types: `add`, `archive`, `update_confidence`
+
+### Changed
+- Memory unit meta fields: `confidence` (0.0-1.0) and `status` (active/stale/archived)
+
+## v0.2.0 — MCP Server + Tests (2026-06-26)
+
+### Added
+- Full MCP (Model Context Protocol) server via `memgrid serve`
+- MCP tools: `memgrid_search`, `memgrid_context`
+- Test suite with Vitest
+- Septonir project integration test
+
+## v0.1.0 — Core Engine (2026-06-26)
+
+### Added
+- TypeScript AST scanning with `ts-morph`: extracts methods, classes, exported functions
+- Rule extraction from `.claude/rules/*.md` (sections → pattern/trigger units)
+- Example extraction from `.claude/examples/` (good/bad patterns)
+- Config extraction from `package.json`, `docker-compose.yml`
+- Association graph building (call graph, pattern matching)
+- CLI: `init`, `search`, `add`, `stats`
+- File-based storage in `.claude/memory-grid/`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wenliangw
+
+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,251 @@
+# MemGrid
+
+> Project-level semantic memory for AI coding agents. Replaces full-codebase context loading with a self-evolving knowledge-mesh.
+
+## 🧠 What is MemGrid?
+
+MemGrid builds a **memory mesh** of your project — not as flat documents, but as interconnected **knowledge units**. Each unit represents one thing: a method, a component, a design pattern, a bug fix, a coding style preference, or a tooling rule.
+
+When an AI coding agent starts a task, instead of dumping your entire codebase into context, MemGrid retrieves only the relevant units — and traverses their associations to pull in related context.
+
+Think of it as **your project's persistent brain** that gets sharper with every task.
+
+## 🎯 The Problem
+
+AI coding tools today face a context dilemma:
+
+- Load the whole project → massive token waste, slow responses, OOM
+- Load only open files → no context, generic output, repeated mistakes
+- Start fresh every session → no learning, inconsistent style
+
+MemGrid solves this by giving the agent exactly what it needs, nothing it doesn't.
+
+## 📐 Architecture
+
+```
+┌─────────────────────────────────────────┐
+│           MemGrid (Agent Brain)          │
+│                                          │
+│  ┌────────────────────────────────────┐  │
+│  │  Scheduler Layer (Meta-Cognition)  │  │
+│  │  skill_trigger / mcp_trigger      │  │
+│  │  rule_trigger                     │  │
+│  │  "What tool for what task"        │  │
+│  └──────────┬─────────────────────────┘  │
+│             │ drives                     │
+│  ┌──────────▼─────────────────────────┐  │
+│  │  Knowledge Layer (Semantics)       │  │
+│  │  method / component / pattern      │  │
+│  │  config / error_solution           │  │
+│  │  "What this project is"             │  │
+│  └──────────┬─────────────────────────┘  │
+│             │ shapes                     │
+│  ┌──────────▼─────────────────────────┐  │
+│  │  Style Layer (Your DNA)            │  │
+│  │  style_preference                  │  │
+│  │  architecture_principle            │  │
+│  │  decision (why we did this)        │  │
+│  │  "What your code looks like"       │  │
+│  └────────────────────────────────────┘  │
+└─────────────────────────────────────────┘
+```
+
+## 🚀 Quick Start
+
+```bash
+npm install -g memgrid
+# or
+pnpm add -g memgrid
+```
+
+### Initialize
+
+```bash
+cd your-project
+memgrid init
+```
+
+MemGrid auto-detects your project's languages and scans all relevant source files.
+
+**Supported languages:** TypeScript, JavaScript, Python, Go, Rust, and any Markdown documentation.
+
+```bash
+# Example output for a TypeScript + Markdown + Rules project:
+# 🔍 Scanning project (typescript, markdown, rules, config)...
+```
+
+The grid is stored in `.claude/memory-grid/`.
+
+### Search
+
+```bash
+# Hybrid search (keyword + semantic, configurable weight)
+memgrid search "add file upload to creation endpoint"
+
+# With options
+memgrid search "error handling pattern" --semantic 0.6 --max 5 --hops 2
+```
+
+### Incremental Sync
+
+Fast sync after code changes — only re-scans changed files:
+
+```bash
+memgrid sync
+# Output:
+# 📁 Changed files:  3
+# 🗑️  Removed files:  0
+# 📝 Updated units:  12
+# ⚠️  Stale units:    0
+# 🔗 Repaired links: 2
+# ⏱️  Done in 1834ms
+```
+
+### Add Custom Units
+
+```bash
+memgrid add \
+  --type decision \
+  --summary "Why we chose PostgreSQL over MongoDB" \
+  --description "ACID compliance for financial data, team expertise, $REASON" \
+  --file docs/decisions/database.md
+```
+
+### Stats
+
+```bash
+memgrid stats
+# 📊 MemGrid Statistics
+#   Total units:    150
+#   Active:         142
+#   Archived:       8
+#   Last scan:      2026-06-28T10:00:00.000Z
+```
+
+### MCP Server
+
+```bash
+memgrid serve
+```
+
+Exposes MemGrid as an MCP tool — plug into Claude Desktop, VS Code, or any MCP-compatible agent.
+
+## 📦 Memory Unit Types
+
+| Type | What it stores | Example |
+|------|---------------|---------|
+| `method` | A function/class method | `CreationDomainService.create()` |
+| `component` | A UI component | `CreationCard` |
+| `pattern` | Design pattern or convention | ResponseBuilder chain pattern |
+| `config` | Configuration/env | Docker services, tech stack |
+| `error_solution` | A bug + how it was fixed | "GLM OOM → switch to DeepSeek" |
+| `decision` | A code decision + rationale | "Why delete returns true, not null" |
+| `skill_trigger` | When to use which skill | "Figma work → enable chakra MCP" |
+| `mcp_trigger` | When to call which MCP | "New Chakra component → get_component_example" |
+| `rule_trigger` | When to load which rule | "Server code → load coding-philosophy" |
+| `style_preference` | Your coding style | "functional pipes over for-loops" |
+| `architecture_principle` | Architecture red lines | "Controller never calls Repository directly" |
+
+## 🆚 vs Alternatives
+
+| | Claude Auto Memory | Mem0 | Cursor Indexing | **MemGrid** |
+|---|---|---|---|---|
+| Granularity | Documents | Conversations | Files | **Knowledge units** |
+| Structure | Flat text | Flat | File tree | **Mesh (graph)** |
+| Retrieval | Full load | Semantic | Semantic | **Hybrid + Traverse** |
+| Learning | Linear append | None | None | **Post-task self-evolution** |
+| Incremental sync | No | No | Full re-index | **Hash-diff incremental** |
+| Tool-aware | No | No | No | **Trigger units** |
+| Style-aware | Rules only | No | No | **Style layer** |
+
+## 📊 Performance
+
+| Scenario | Time |
+|----------|------|
+| Search (keyword) | < 3ms |
+| Search (repeated, LRU) | 0ms |
+| Sync (0 changes) | ~5ms |
+| Sync (1 file changed) | ~2s |
+| Full init (150 units) | ~10s |
+
+## 📁 File Format
+
+Memory units are stored as JSON in `.claude/memory-grid/units/` — **Git-friendly and human-readable**.
+
+```json
+{
+  "id": "method_creation_create",
+  "type": "method",
+  "summary": "CreationDomainService.create — Create a new work",
+  "source": {
+    "file": "apps/server/src/creation/creation.domain-service.ts",
+    "lines": "45-67"
+  },
+  "signatures": ["CreationDomainService.create"],
+  "content": {
+    "description": "Creates a new work, verifies ownership, saves to DB",
+    "inputs": "userId: string, dto: Partial<CreationEntity>",
+    "outputs": "ApiResponse{ value: savedEntity }"
+  },
+  "associations": [
+    {
+      "to": "pattern_response_builder",
+      "relation": "implements_pattern",
+      "weight": 0.9
+    }
+  ],
+  "meta": {
+    "created": "2026-06-28T00:00:00.000Z",
+    "updated": "2026-06-28T00:00:00.000Z",
+    "confidence": 0.8,
+    "usage_count": 0,
+    "status": "active"
+  }
+}
+```
+
+`mesh.json` stores the grid metadata including `fileSnapshot` for incremental sync and `edgeIndex` for fast association traversal.
+
+## 🌐 Language Support
+
+MemGrid is **language-agnostic** at its core. Scanners are swappable plugins:
+
+| Scanner | Detects | Extracts |
+|---------|---------|----------|
+| **TypeScript** | `tsconfig.json`, `.ts` files | Classes, methods, exported functions (AST via ts-morph) |
+| **JavaScript** | `package.json` (no tsconfig), `.js` files | Exported functions, classes, arrow functions (regex) |
+| **Python** | `pyproject.toml`, `.py` files | Functions, classes, decorators, docstrings (regex) |
+| **Go** | `go.mod`, `.go` files | Functions, methods, structs, interfaces (regex) |
+| **Rust** | `Cargo.toml`, `.rs` files | Functions, structs, enums, traits, impl blocks (regex) |
+| **Markdown** | Any `.md` files | Headings as knowledge units |
+| **Rules** | `.claude/rules/*.md` | Design patterns, coding rules, trigger units |
+| **Config** | `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `docker-compose.yml` | Tech stack, dependencies, infrastructure |
+
+**Adding a new language** means implementing the `Scanner` interface — the core engine (storage, retrieval, learning, sync) stays untouched.
+
+```typescript
+// src/scanner/python.ts (example)
+export class PythonScanner implements Scanner {
+  readonly name = 'python';
+  detect(projectRoot: string): boolean { ... }
+  async scan(options: ScanOptions): Promise<MemoryUnit[]> { ... }
+}
+```
+
+## 🔌 Integration
+
+MemGrid outputs **standardized Markdown context** consumable by any AI coding tool:
+
+- **Claude Code** — via MCP Server or Hook
+- **Cursor / Windsurf** — via Rules file injection
+- **GitHub Copilot** — via `.github/copilot-instructions.md`
+- **Aider / Cline / Continue** — via custom prompt templates
+
+```bash
+# Start MCP Server
+memgrid serve
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { MemGrid } from './memgrid.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { MemGrid } from './memgrid.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/learn/index.d.ts

@@ -0,0 +1,44 @@
+import type { MemoryUnit } from '../shared/types.js';
+import type { FileStore } from '../store/file-store.js';
+export interface TaskResult {
+    summary: string;
+    outcome: string;
+    filesModified: string[];
+    errorsEncountered?: string[];
+    decisions?: string[];
+    toolsUsed?: string[];
+    styleObservations?: string[];
+}
+export interface LearningSuggestions {
+    add: Partial<MemoryUnit>[];
+    update: {
+        id: string;
+        patch: Partial<MemoryUnit>;
+    }[];
+    archive: string[];
+    summary: string;
+}
+export declare class LearnEngine {
+    private store;
+    private retrieve;
+    constructor(store: FileStore);
+    /**
+     * Analyze a completed task and suggest memory grid updates.
+     * This is the core "self-learning" loop — called after every task.
+     */
+    analyze(task: TaskResult): Promise<LearningSuggestions>;
+    /**
+     * Apply the learning suggestions to the grid.
+     * Only applies units with confidence >= 0.7 by default.
+     */
+    apply(suggestions: LearningSuggestions, minConfidence?: number): Promise<string[]>;
+    /**
+     * Generate a plain text summary of suggestions for display/copy.
+     */
+    formatSuggestions(suggestions: LearningSuggestions): string;
+    /**
+     * Infer the domain/subject area from a task summary.
+     */
+    private inferDomain;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/learn/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/learn/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAkB,MAAM,oBAAoB,CAAC;AACrE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGxD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;IAC3B,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,CAAA;KAAE,EAAE,CAAC;IACrD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,KAAK,CAAY;IACzB,OAAO,CAAC,QAAQ,CAAiB;gBAErB,KAAK,EAAE,SAAS;IAK5B;;;OAGG;IACG,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAyI7D;;;OAGG;IACG,KAAK,CAAC,WAAW,EAAE,mBAAmB,EAAE,aAAa,SAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAkDrF;;OAEG;IACH,iBAAiB,CAAC,WAAW,EAAE,mBAAmB,GAAG,MAAM;IAgC3D;;OAEG;IACH,OAAO,CAAC,WAAW;CAoBpB"}

package/dist/learn/index.js

@@ -0,0 +1,234 @@
+import { RetrieveEngine } from '../retrieve/index.js';
+export class LearnEngine {
+    store;
+    retrieve;
+    constructor(store) {
+        this.store = store;
+        this.retrieve = new RetrieveEngine(store);
+    }
+    /**
+     * Analyze a completed task and suggest memory grid updates.
+     * This is the core "self-learning" loop — called after every task.
+     */
+    async analyze(task) {
+        const suggestions = {
+            add: [],
+            update: [],
+            archive: [],
+            summary: '',
+        };
+        const summaries = [];
+        // 1. Suggest new method units for modified files
+        if (task.filesModified.length > 0) {
+            const existingUnits = await this.store.listUnits();
+            const existingFiles = new Set(existingUnits
+                .filter((u) => u.source?.file)
+                .map((u) => u.source.file));
+            const newFiles = task.filesModified.filter((f) => !existingFiles.has(f));
+            if (newFiles.length > 0) {
+                summaries.push(`🆕 ${newFiles.length} new files to scan`);
+                // Don't actually scan here — just flag for memgrid init
+                for (const file of newFiles) {
+                    suggestions.add.push({
+                        type: 'method',
+                        summary: `[TODO] New file: ${file}`,
+                        content: {
+                            description: `This file was created/modified in task: "${task.summary}". Run \`memgrid init\` to scan for method units.`,
+                            trigger: `When working near ${file}`,
+                            action: `Rescan with memgrid init`,
+                        },
+                        source: { file },
+                    });
+                }
+            }
+        }
+        // 2. Suggest error_solution units
+        if (task.errorsEncountered && task.errorsEncountered.length > 0) {
+            for (const error of task.errorsEncountered) {
+                const id = `error_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+                suggestions.add.push({
+                    type: 'error_solution',
+                    summary: `Error fix: ${error.slice(0, 80)}`,
+                    content: {
+                        description: error,
+                    },
+                });
+            }
+            summaries.push(`🐛 ${task.errorsEncountered.length} error(s) recorded as error_solution units`);
+        }
+        // 3. Suggest decision units
+        if (task.decisions && task.decisions.length > 0) {
+            for (const decision of task.decisions) {
+                const id = `decision_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+                suggestions.add.push({
+                    type: 'decision',
+                    summary: decision.slice(0, 80),
+                    content: {
+                        description: `Design decision from task "${task.summary}": ${decision}`,
+                    },
+                });
+            }
+            summaries.push(`🎯 ${task.decisions.length} decision(s) recorded`);
+        }
+        // 4. Suggest trigger units based on tools used
+        if (task.toolsUsed && task.toolsUsed.length > 0) {
+            for (const tool of task.toolsUsed) {
+                // Check if a similar trigger already exists
+                const existing = (await this.store.listUnits()).find((u) => u.type === 'skill_trigger' && u.summary.includes(tool));
+                if (!existing) {
+                    const id = `trigger_skill_${tool.replace(/[^a-z0-9_]/g, '_')}_${Date.now()}`;
+                    suggestions.add.push({
+                        type: 'skill_trigger',
+                        summary: `When working on ${this.inferDomain(task.summary)} → use ${tool}`,
+                        content: {
+                            description: `Task "${task.summary}" successfully used ${tool}`,
+                            trigger: this.inferDomain(task.summary),
+                            action: `Enable and use ${tool}`,
+                        },
+                    });
+                }
+            }
+            summaries.push(`🔧 ${task.toolsUsed.length} tool trigger(s) suggested`);
+        }
+        // 5. Suggest style_preference units based on observations
+        if (task.styleObservations && task.styleObservations.length > 0) {
+            for (const style of task.styleObservations) {
+                const id = `style_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+                suggestions.add.push({
+                    type: 'style_preference',
+                    summary: style.slice(0, 80),
+                    content: {
+                        description: `Observed in task "${task.summary}": ${style}`,
+                        style_notes: style,
+                    },
+                });
+            }
+            summaries.push(`🎨 ${task.styleObservations.length} style preference(s) recorded`);
+        }
+        // 6. Check for units that might need archiving (stale — referenced files deleted)
+        const allUnits = await this.store.listUnits();
+        for (const unit of allUnits.filter((u) => u.type === 'method')) {
+            if (unit.source?.file && task.filesModified.includes(unit.source.file)) {
+                // File was modified — flag for review
+                suggestions.update.push({
+                    id: unit.id,
+                    patch: {
+                        meta: {
+                            ...unit.meta,
+                            status: 'stale',
+                            updated: new Date().toISOString(),
+                        },
+                    },
+                });
+            }
+        }
+        // 7. Build summary
+        if (summaries.length === 0) {
+            suggestions.summary = 'No significant new knowledge to add. Grid is stable for this task.';
+        }
+        else {
+            suggestions.summary = summaries.join('\n');
+        }
+        return suggestions;
+    }
+    /**
+     * Apply the learning suggestions to the grid.
+     * Only applies units with confidence >= 0.7 by default.
+     */
+    async apply(suggestions, minConfidence = 0.7) {
+        const applied = [];
+        for (const unit of suggestions.add) {
+            const fullUnit = {
+                id: `auto_${unit.type}_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`,
+                type: unit.type,
+                summary: unit.summary || 'Unknown',
+                signatures: unit.signatures || [],
+                content: unit.content || { description: '' },
+                source: unit.source,
+                associations: [],
+                meta: {
+                    created: new Date().toISOString(),
+                    updated: new Date().toISOString(),
+                    confidence: 0.6, // Auto-generated, lower confidence
+                    usage_count: 0,
+                    status: 'active',
+                },
+            };
+            if (fullUnit.meta.confidence >= minConfidence) {
+                this.store.saveUnit(fullUnit);
+                applied.push(`+ ${fullUnit.id}`);
+            }
+            else {
+                // Save anyway but mark as needs-review
+                fullUnit.meta.status = 'stale'; // stale here means "pending human review"
+                this.store.saveUnit(fullUnit);
+                applied.push(`? ${fullUnit.id} (needs review, confidence: ${fullUnit.meta.confidence})`);
+            }
+        }
+        for (const { id, patch } of suggestions.update) {
+            const existing = this.store.getUnit(id);
+            if (existing) {
+                Object.assign(existing, patch);
+                existing.meta.updated = new Date().toISOString();
+                this.store.saveUnit(existing);
+                applied.push(`~ ${id} (updated)`);
+            }
+        }
+        for (const id of suggestions.archive) {
+            this.store.archiveUnit(id);
+            applied.push(`- ${id} (archived)`);
+        }
+        return applied;
+    }
+    /**
+     * Generate a plain text summary of suggestions for display/copy.
+     */
+    formatSuggestions(suggestions) {
+        const lines = ['## 📋 Learning Suggestions', '', suggestions.summary, ''];
+        if (suggestions.add.length > 0) {
+            lines.push(`### Add (${suggestions.add.length})`, '');
+            for (const unit of suggestions.add) {
+                lines.push(`- [${unit.type}] ${unit.summary}`);
+            }
+            lines.push('');
+        }
+        if (suggestions.update.length > 0) {
+            lines.push(`### Update (${suggestions.update.length})`, '');
+            for (const { id, patch } of suggestions.update) {
+                const status = patch.meta?.status || 'changed';
+                lines.push(`- \`${id}\` → ${status}`);
+            }
+            lines.push('');
+        }
+        if (suggestions.archive.length > 0) {
+            lines.push(`### Archive (${suggestions.archive.length})`, '');
+            for (const id of suggestions.archive) {
+                lines.push(`- \`${id}\``);
+            }
+            lines.push('');
+        }
+        lines.push('---', 'Run `memgrid apply-suggestions` to apply all changes.');
+        return lines.join('\n');
+    }
+    /**
+     * Infer the domain/subject area from a task summary.
+     */
+    inferDomain(summary) {
+        const domains = {
+            'server code': ['server', 'api', 'controller', 'service', 'nest', 'typeorm', 'postgres', 'database', 'auth'],
+            'frontend': ['web', 'ui', 'component', 'page', 'chakra', 'react', 'next', 'figma', 'style', 'css'],
+            'config': ['config', 'env', 'docker', 'ci', 'deploy', 'package'],
+            'review': ['pr', 'review', 'merge', 'branch'],
+            'docs': ['docs', 'readme', 'documentation'],
+            'memory': ['memory', 'grid', 'atom'],
+        };
+        const lower = summary.toLowerCase();
+        for (const [domain, keywords] of Object.entries(domains)) {
+            if (keywords.some((k) => lower.includes(k))) {
+                return domain;
+            }
+        }
+        return 'generic development tasks';
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/learn/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/learn/index.ts"],"names":[],"mappings":"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"}