stellar-memory 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 sangjun0000
+
+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,362 @@
+# Stellar Memory
+
+**Persistent AI memory powered by celestial mechanics.**
+
+Important memories orbit close to the Sun. Forgotten ones drift to the Oort Cloud.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js 22+](https://img.shields.io/badge/Node.js-22%2B-green.svg)](https://nodejs.org)
+[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org)
+
+---
+
+Stellar Memory is a local-first, persistent memory system for AI assistants. It uses **orbital mechanics as a cognitive model** -- memories with high importance orbit close to the Sun for instant recall, while stale knowledge naturally drifts outward through exponential decay. No cloud services, no API keys, no data leaving your machine.
+
+## Key Features
+
+- **Orbital Importance Model** -- 4-factor scoring (recency, frequency, impact, relevance) maps each memory to an orbital distance from 0.1 to 100 AU
+- **Hybrid Search** -- FTS5 keyword search + sqlite-vec KNN vector search, merged via Reciprocal Rank Fusion
+- **Local Embeddings** -- all-MiniLM-L6-v2 (384d) runs entirely in-process via `@xenova/transformers`
+- **Corona Cache** -- in-memory tier of up to 200 core memories for sub-millisecond recall
+- **MCP Native** -- 16 tools + 1 resource, works with Claude Code, Claude Desktop, and any MCP client
+- **REST API** -- Hono server on port 21547 with 13 route groups
+- **3D Dashboard** -- React + Three.js solar system visualization with D3 orbital overlay
+- **Multi-Project** -- isolated memory spaces (galaxies) with cross-project universal memories
+- **Knowledge Graph** -- constellation of typed relationships between memories
+- **Temporal Awareness** -- time-bounded memories, evolution chains, point-in-time queries
+- **Conflict Detection** -- automatic detection of contradicting memories with resolution workflow
+- **Quality Scoring** -- specificity, actionability, uniqueness, freshness metrics per memory
+- **Procedural Memories** -- auto-discovered behavioral patterns that decay 3.3x slower
+- **Background Daemon** -- scheduled orbit recalculation, decay, and consolidation
+- **Zero Dependencies on Cloud** -- everything runs locally with `node:sqlite` and local embeddings
+
+## How It Works
+
+```
+                         importance = 0.30 x recency
+                                    + 0.20 x frequency
+                                    + 0.30 x impact
+                                    + 0.20 x relevance
+
+         distance = 0.1 + (1 - importance)^2 x 99.9
+
+    .  *  .        .          *       .        .     *   .
+         .    * .        .        .        .
+              .  CORE (0.1-1 AU)     .
+      .    .  instant recall     .    *
+         *   . . . . . . . .  .         .
+       .  NEAR (1-5 AU)  .        .
+      .   recently used   .    *         .
+         . . . . . . . . . .       .          *
+    .  ACTIVE (5-15 AU)       .        .
+       in-context memories   .    .         .
+      . . . . . . . . . . . . .     *          .
+    ARCHIVE (15-40 AU)     .           .
+      older knowledge    .       .          .
+      . . . . . . . . . . . . . . .   *
+     FADING (40-70 AU)          .         .
+       losing relevance       .     .        .
+      . . . . . . . . . . . . . . . . . .
+     FORGOTTEN (70-100 AU)              .
+       the Oort Cloud -- soft deleted     .
+```
+
+When you recall a memory, it gets pulled closer to the Sun. When you stop using it, exponential decay pushes it outward. The half-life is 72 hours by default.
+
+## Quick Start
+
+### Prerequisites
+
+- **Node.js 22+** (required for built-in `node:sqlite`)
+- **npm 9+**
+
+### Install
+
+```bash
+git clone https://github.com/your-username/stellar-memory.git
+cd stellar-memory
+npm install
+npm run build
+```
+
+### Use with Claude Code (MCP)
+
+Add to your Claude Code MCP settings (`~/.claude/settings.json` or project `.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "stellar-memory": {
+      "command": "node",
+      "args": ["/absolute/path/to/stellar-memory/dist/index.js"],
+      "env": {
+        "STELLAR_PROJECT": "my-project"
+      }
+    }
+  }
+}
+```
+
+Then in Claude Code, Stellar Memory automatically:
+1. Reads `stellar://sun` to restore working context at session start
+2. Recalls relevant memories when topics change
+3. Stores decisions, errors, and milestones as they happen
+4. Commits session state before the conversation ends
+
+### Use with Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "stellar-memory": {
+      "command": "node",
+      "args": ["/absolute/path/to/stellar-memory/dist/index.js"],
+      "env": {
+        "STELLAR_PROJECT": "my-project"
+      }
+    }
+  }
+}
+```
+
+### Run the Dashboard
+
+```bash
+# Start the API server
+npm run api
+
+# In another terminal, start the web dashboard
+cd web && npm run dev
+```
+
+Open http://localhost:5175 to see your memories orbiting in 3D.
+
+### Run the Background Daemon
+
+```bash
+npm run daemon
+```
+
+The daemon runs scheduled tasks:
+| Task | Interval |
+|------|----------|
+| Orbit recalculation | 1 hour |
+| Memory decay | 6 hours |
+| Consolidation check | 24 hours |
+
+## System Requirements
+
+| Requirement | Minimum |
+|-------------|---------|
+| Node.js | 22.0.0+ (for `node:sqlite`) |
+| npm | 9.0.0+ |
+| Disk | ~100 MB (embedding model) + DB |
+| RAM | ~200 MB (model + corona cache) |
+| OS | Windows, macOS, Linux |
+
+The embedding model (~90 MB) downloads automatically on first use and is cached in `~/.cache/huggingface`.
+
+## Configuration
+
+All configuration is via environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `STELLAR_DB_PATH` | `~/.stellar-memory/stellar.db` | SQLite database file location |
+| `STELLAR_PROJECT` | `default` | Active project name |
+| `STELLAR_API_PORT` | `21547` | REST API port |
+| `STELLAR_SUN_TOKEN_BUDGET` | `800` | Max tokens for sun context resource |
+| `STELLAR_DECAY_HALF_LIFE` | `72` | Hours for 50% recency decay |
+| `STELLAR_WEIGHT_RECENCY` | `0.30` | Weight for recency in importance formula |
+| `STELLAR_WEIGHT_FREQUENCY` | `0.20` | Weight for access frequency |
+| `STELLAR_WEIGHT_IMPACT` | `0.30` | Weight for memory type impact |
+| `STELLAR_WEIGHT_RELEVANCE` | `0.20` | Weight for contextual relevance |
+
+## Architecture
+
+### Project Structure
+
+```
+src/
+  engine/          Core: orbit, gravity, corona, embedding, quality, analytics
+  storage/         database.ts, queries.ts, vec.ts (sqlite-vec)
+  mcp/             MCP server + tools (memory-tools, ingestion-tools, daemon-tool)
+  api/             Hono REST server + 12 route modules
+  scanner/         Filesystem + git log scanners with file parsers
+  service/         Background daemon + scheduler
+  utils/           Config, logger, tokenizer, time helpers
+
+web/src/
+  components/      SolarSystem (Three.js), Layout, SearchBar, MemoryDetail, etc.
+  api/client.ts    REST API client
+  i18n/            EN/KO internationalization (React Context)
+
+tests/             15 test files, 252 tests (Vitest)
+electron/          Desktop app (Electron 40)
+```
+
+### Database
+
+SQLite via Node.js built-in `node:sqlite` with three search layers:
+
+1. **memories** table -- structured storage with 20+ columns
+2. **memories_fts** -- FTS5 virtual table for keyword search
+3. **memory_vec** -- sqlite-vec virtual table for 384-dimension KNN search
+
+### Search Pipeline
+
+```
+Query
+  |
+  +---> FTS5 keyword search ----+
+  |                              |---> Reciprocal Rank Fusion ---> Re-ranked results
+  +---> sqlite-vec KNN search --+
+```
+
+The hybrid approach handles both exact matches ("JWT authentication error") and semantic matches ("login token expired").
+
+### Corona Cache
+
+An in-memory tier holding up to 200 core + near zone memories with a token index for O(1) keyword lookup. The corona mirrors how human System 1 thinking works -- your most important knowledge is always instantly available.
+
+## MCP Tools Reference
+
+| Tool | Description |
+|------|-------------|
+| `status` | View memory system state, grouped by orbital zone |
+| `recall` | Hybrid search -- finds memories and pulls them closer |
+| `remember` | Store a new memory with type, impact, and tags |
+| `forget` | Push a memory to the Oort Cloud or permanently delete it |
+| `commit` | Save session state to the Sun (working context) |
+| `orbit` | Force recalculation of all orbital positions |
+| `scan` | Ingest a local directory into memories (idempotent) |
+| `daemon` | Start/stop/status of the background scheduler |
+| `constellation` | Explore the knowledge graph between memories |
+| `galaxy` | Multi-project management (switch, list, universal memories) |
+| `analytics` | System insights: health, topics, survival curves, movements |
+| `observe` | Auto-extract memories from conversation text |
+| `consolidate` | Find and merge duplicate/similar memories |
+| `resolve_conflict` | View and resolve contradicting memories |
+| `temporal` | Point-in-time queries and memory evolution chains |
+| `export` | Backup memories as JSON or Markdown |
+
+### Resource
+
+| URI | Description |
+|-----|-------------|
+| `stellar://sun` | Current working context (core + near memories within token budget) |
+
+## REST API
+
+The API server runs on port 21547 (default) and exposes:
+
+```
+GET    /api/health                    Health check
+GET    /api/memories                  List memories (with filters)
+POST   /api/memories                  Create a memory
+GET    /api/memories/:id              Get a single memory
+PATCH  /api/memories/:id              Update a memory
+DELETE /api/memories/:id              Delete a memory
+GET    /api/sun                       Get sun state
+POST   /api/sun/commit                Commit session state
+POST   /api/orbit/recalculate         Trigger orbit recalculation
+GET    /api/constellation/:id         Get knowledge graph
+GET    /api/projects                  List projects
+POST   /api/projects                  Create a project
+GET    /api/analytics/:report         Get analytics report
+GET    /api/temporal/at               Point-in-time query
+GET    /api/conflicts                 List conflicts
+POST   /api/scan                      Scan a directory
+GET    /api/sources                   List data sources
+POST   /api/observations              Submit conversation for observation
+POST   /api/consolidation             Run consolidation
+```
+
+## Development
+
+```bash
+# Run MCP server in dev mode (stdio, watch)
+npm run dev
+
+# Run API server in dev mode (watch)
+npm run api
+
+# Run web dashboard (proxies /api to :21547)
+cd web && npm run dev
+
+# Run all tests
+npm run test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Build everything
+npm run build:all
+
+# Build Electron desktop app
+npm run electron:pack
+```
+
+## Troubleshooting
+
+### "Cannot find module 'node:sqlite'"
+
+You need Node.js 22 or later. The `node:sqlite` module is a built-in that was added in Node.js 22.
+
+```bash
+node --version  # Must be >= 22.0.0
+```
+
+### Embedding model download hangs
+
+The all-MiniLM-L6-v2 model (~90 MB) downloads from Hugging Face on first use. If it hangs:
+
+1. Check your internet connection
+2. Try setting a proxy: `export HTTPS_PROXY=http://your-proxy:port`
+3. The model caches to `~/.cache/huggingface` -- delete that directory to force re-download
+
+### sqlite-vec load failure
+
+The `sqlite-vec` extension uses a native binary. If it fails to load:
+
+1. Ensure you ran `npm install` (the binary is fetched during install)
+2. On some platforms, you may need to build from source -- see [sqlite-vec docs](https://github.com/asg017/sqlite-vec)
+3. Stellar Memory works without sqlite-vec (falls back to keyword-only search)
+
+### "SQLITE_ERROR: database is locked"
+
+Only one process should write to the database at a time. If you're running both the MCP server and API server, they share the same database file and SQLite handles locking. If you see this error:
+
+1. Check for zombie processes: `ps aux | grep stellar`
+2. Ensure you're not running multiple MCP server instances
+
+### Web dashboard shows no memories
+
+1. Confirm the API server is running: `curl http://localhost:21547/api/health`
+2. Confirm the web dev server proxies correctly (check `web/vite.config.ts`)
+3. Check browser console for CORS errors
+
+## Testing
+
+```bash
+# Run the full test suite (252 tests)
+npm run test
+
+# Run with coverage
+npx vitest run --coverage
+
+# Run specific test file
+npx vitest run tests/orbit.test.ts
+
+# Web component tests
+cd web && npm run test
+```
+
+The test suite uses a virtual module plugin in `vitest.config.ts` to bridge `node:sqlite` for Vite's module resolver. This is required because Vite does not natively recognize Node.js built-in modules with the `node:` prefix.
+
+## License
+
+MIT

package/dist/api/routes/analytics.d.ts

@@ -0,0 +1,15 @@
+/**
+ * routes/analytics.ts — Memory Analytics API routes
+ *
+ * GET /api/analytics/overview      — full MemoryAnalytics object
+ * GET /api/analytics/survival      — survival curve (age buckets)
+ * GET /api/analytics/movements     — orbit movement timeline
+ * GET /api/analytics/clusters      — topic cluster heatmap
+ * GET /api/analytics/patterns      — periodic access pattern detection
+ * GET /api/analytics/health        — health metrics + recommendations
+ * GET /api/analytics/report        — full text report
+ */
+import { Hono } from 'hono';
+declare const app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+export default app;
+//# sourceMappingURL=analytics.d.ts.map

package/dist/api/routes/analytics.js

@@ -0,0 +1,131 @@
+/**
+ * routes/analytics.ts — Memory Analytics API routes
+ *
+ * GET /api/analytics/overview      — full MemoryAnalytics object
+ * GET /api/analytics/survival      — survival curve (age buckets)
+ * GET /api/analytics/movements     — orbit movement timeline
+ * GET /api/analytics/clusters      — topic cluster heatmap
+ * GET /api/analytics/patterns      — periodic access pattern detection
+ * GET /api/analytics/health        — health metrics + recommendations
+ * GET /api/analytics/report        — full text report
+ */
+import { Hono } from 'hono';
+import { getFullAnalytics, getSurvivalCurve, getOrbitMovements, getTopicClusters, detectAccessPatterns, getMemoryHealth, generateReport, } from '../../engine/analytics.js';
+const app = new Hono();
+// GET /api/analytics/overview
+app.get('/overview', (c) => {
+    const project = c.req.query('project') ?? 'default';
+    try {
+        const data = getFullAnalytics(project);
+        return c.json({ ok: true, data, project });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Analytics failed';
+        return c.json({ ok: false, error: message }, 500);
+    }
+});
+// GET /api/analytics/survival
+app.get('/survival', (c) => {
+    const project = c.req.query('project') ?? 'default';
+    try {
+        const data = getSurvivalCurve(project);
+        return c.json({ ok: true, data, project });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Survival curve failed';
+        return c.json({ ok: false, error: message }, 500);
+    }
+});
+// GET /api/analytics/movements?days=30
+app.get('/movements', (c) => {
+    const project = c.req.query('project') ?? 'default';
+    const daysParam = c.req.query('days');
+    const days = daysParam ? parseInt(daysParam, 10) : 30;
+    try {
+        const data = getOrbitMovements(project, days > 0 ? days : 30);
+        return c.json({ ok: true, data, project, days });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Movements failed';
+        return c.json({ ok: false, error: message }, 500);
+    }
+});
+// GET /api/analytics/clusters
+app.get('/clusters', (c) => {
+    const project = c.req.query('project') ?? 'default';
+    try {
+        const data = getTopicClusters(project);
+        return c.json({ ok: true, data, project });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Clusters failed';
+        return c.json({ ok: false, error: message }, 500);
+    }
+});
+// GET /api/analytics/patterns
+app.get('/patterns', (c) => {
+    const project = c.req.query('project') ?? 'default';
+    try {
+        const data = detectAccessPatterns(project);
+        return c.json({ ok: true, data, project });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Patterns failed';
+        return c.json({ ok: false, error: message }, 500);
+    }
+});
+// GET /api/analytics/health
+app.get('/health', (c) => {
+    const project = c.req.query('project') ?? 'default';
+    try {
+        const data = getMemoryHealth(project);
+        return c.json({ ok: true, data, project });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Health check failed';
+        return c.json({ ok: false, error: message }, 500);
+    }
+});
+// GET /api/analytics/report
+app.get('/report', (c) => {
+    const project = c.req.query('project') ?? 'default';
+    try {
+        const text = generateReport(project);
+        const accept = c.req.header('accept') ?? '';
+        if (accept.includes('text/plain')) {
+            return c.text(text);
+        }
+        return c.json({ ok: true, data: text, project });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Report failed';
+        return c.json({ ok: false, error: message }, 500);
+    }
+});
+// Aliases for new naming convention
+// GET /api/analytics/summary — alias for overview
+app.get('/summary', (c) => {
+    const project = c.req.query('project') ?? 'default';
+    try {
+        const data = getFullAnalytics(project);
+        return c.json({ ok: true, data, project });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Analytics summary failed';
+        return c.json({ ok: false, error: message }, 500);
+    }
+});
+// GET /api/analytics/topics — alias for clusters
+app.get('/topics', (c) => {
+    const project = c.req.query('project') ?? 'default';
+    try {
+        const data = getTopicClusters(project);
+        return c.json({ ok: true, data, project });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Topics failed';
+        return c.json({ ok: false, error: message }, 500);
+    }
+});
+export default app;
+//# sourceMappingURL=analytics.js.map

package/dist/api/routes/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../../../src/api/routes/analytics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,cAAc,GACf,MAAM,2BAA2B,CAAC;AAEnC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;AAEvB,8BAA8B;AAC9B,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE;IACzB,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC;IACpD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACvC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC;QACxE,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,CAAC,CAAC;IACpD,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,8BAA8B;AAC9B,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE;IACzB,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC;IACpD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACvC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,uBAAuB,CAAC;QAC7E,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,CAAC,CAAC;IACpD,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,uCAAuC;AACvC,GAAG,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE;IAC1B,MAAM,OAAO,GAAK,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC;IACtD,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACtC,MAAM,IAAI,GAAQ,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3D,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,iBAAiB,CAAC,OAAO,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC9D,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC;QACxE,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,CAAC,CAAC;IACpD,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,8BAA8B;AAC9B,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE;IACzB,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC;IACpD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACvC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC;QACvE,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,CAAC,CAAC;IACpD,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,8BAA8B;AAC9B,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,EAAE;IACzB,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC;IACpD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAC3C,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC;QACvE,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,CAAC,CAAC;IACpD,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,4BAA4B;AAC5B,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE;IACvB,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC;IACpD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;QACtC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,qBAAqB,CAAC;QAC3E,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,CAAC,CAAC;IACpD,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,4BAA4B;AAC5B,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE;IACvB,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC;IACpD,IAAI,CAAC;QACH,MAAM,IAAI,GAAK,cAAc,CAAC,OAAO,CAAC,CAAC;QACvC,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC5C,IAAI,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;YAClC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;QACD,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;QACrE,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,CAAC,CAAC;IACpD,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,oCAAoC;AACpC,kDAAkD;AAClD,GAAG,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE;IACxB,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC;IACpD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACvC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,0BAA0B,CAAC;QAChF,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,CAAC,CAAC;IACpD,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,iDAAiD;AACjD,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE;IACvB,MAAM,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC;IACpD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACvC,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;QACrE,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,GAAG,CAAC,CAAC;IACpD,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,eAAe,GAAG,CAAC"}

package/dist/api/routes/conflicts.d.ts

@@ -0,0 +1,12 @@
+/**
+ * routes/conflicts.ts — Memory Conflict API routes
+ *
+ * GET  /api/conflicts                 — getUnresolvedConflicts (query: project)
+ * GET  /api/conflicts/:memoryId       — getConflictsForMemory
+ * POST /api/conflicts/:id/resolve     — resolveConflict
+ * POST /api/conflicts/:id/dismiss     — resolveConflict with dismiss action
+ */
+import { Hono } from 'hono';
+declare const app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+export default app;
+//# sourceMappingURL=conflicts.d.ts.map

package/dist/api/routes/conflicts.js

@@ -0,0 +1,67 @@
+/**
+ * routes/conflicts.ts — Memory Conflict API routes
+ *
+ * GET  /api/conflicts                 — getUnresolvedConflicts (query: project)
+ * GET  /api/conflicts/:memoryId       — getConflictsForMemory
+ * POST /api/conflicts/:id/resolve     — resolveConflict
+ * POST /api/conflicts/:id/dismiss     — resolveConflict with dismiss action
+ */
+import { Hono } from 'hono';
+import { getUnresolvedConflicts, resolveConflict, } from '../../engine/conflict.js';
+import { getConflictsForMemory } from '../../storage/queries.js';
+const app = new Hono();
+// GET /api/conflicts?project=default
+app.get('/', (c) => {
+    const project = c.req.query('project') ?? 'default';
+    try {
+        const data = getUnresolvedConflicts(project);
+        return c.json({ ok: true, data, project, total: data.length });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Get conflicts failed';
+        return c.json({ ok: false, error: message }, 500);
+    }
+});
+// GET /api/conflicts/:memoryId — get conflicts for a specific memory
+app.get('/:memoryId', (c) => {
+    const memoryId = c.req.param('memoryId');
+    try {
+        const data = getConflictsForMemory(memoryId);
+        return c.json({ ok: true, data, memoryId, total: data.length });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Get conflicts for memory failed';
+        return c.json({ ok: false, error: message }, 500);
+    }
+});
+// POST /api/conflicts/:id/resolve — body: { resolution, action? }
+app.post('/:id/resolve', async (c) => {
+    const id = c.req.param('id');
+    try {
+        const body = await c.req.json();
+        const resolution = body.resolution ?? 'Resolved via API';
+        const action = body.action ?? 'supersede';
+        resolveConflict(id, resolution, action);
+        return c.json({ ok: true, id, action, resolution });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Resolve conflict failed';
+        return c.json({ ok: false, error: message }, 500);
+    }
+});
+// POST /api/conflicts/:id/dismiss — shortcut for dismiss action
+app.post('/:id/dismiss', async (c) => {
+    const id = c.req.param('id');
+    try {
+        const body = await c.req.json().catch(() => ({}));
+        const resolution = body.resolution ?? 'Dismissed via API';
+        resolveConflict(id, resolution, 'dismiss');
+        return c.json({ ok: true, id, action: 'dismiss', resolution });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : 'Dismiss conflict failed';
+        return c.json({ ok: false, error: message }, 500);
+    }
+});
+export default app;
+//# sourceMappingURL=conflicts.js.map

package/dist/api/routes/conflicts.js.map

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

package/dist/api/routes/consolidation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * routes/consolidation.ts — Memory Consolidation API routes
+ *
+ * GET  /api/consolidation/candidates      — findConsolidationCandidates
+ * POST /api/consolidation/run             — runConsolidation
+ * GET  /api/consolidation/history/:id     — getConsolidationSources
+ */
+import { Hono } from 'hono';
+declare const app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+export default app;
+//# sourceMappingURL=consolidation.d.ts.map