shelbymcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Studio Moser
+
+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,335 @@
+<p align="center">
+  <img src="docs/assets/shelby-mcp-header.png" alt="ShelbyMCP" width="720" />
+</p>
+
+<p align="center">
+  <strong>The knowledge-graph memory server for AI tools.</strong><br/>
+  Mem0-grade intelligence. Engram-grade simplicity.
+</p>
+
+<p align="center">
+  <a href="#quick-start"><strong>Quick Start</strong></a> ·
+  <a href="docs/ARCHITECTURE.md"><strong>Architecture</strong></a> ·
+  <a href="docs/AGENT-SETUP.md"><strong>Agent Setup</strong></a> ·
+  <a href="#contributing"><strong>Contributing</strong></a>
+</p>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" /></a>
+  <a href="https://github.com/Studio-Moser/shelbymcp/stargazers"><img src="https://img.shields.io/github/stars/Studio-Moser/shelbymcp?style=flat" alt="Stars" /></a>
+</p>
+
+---
+
+## What is ShelbyMCP?
+
+Every AI memory server is a bag of embeddings. **ShelbyMCP connects your thoughts.**
+
+ShelbyMCP is a zero-dependency MCP memory server with a built-in knowledge graph. It gives Claude Code, Cursor, Codex, Windsurf, and any MCP-compatible AI tool persistent memory that understands how your thoughts are related — not just what they contain.
+
+Ship it with the **Forage skill**, a scheduled task that runs on your existing AI subscription to continuously enrich, consolidate, and connect your memories. No Docker. No Python. No cloud accounts. Just a binary and a database file.
+
+### Why ShelbyMCP?
+
+| Problem | ShelbyMCP's answer |
+|---|---|
+| Every conversation starts from zero | Persistent memory across sessions |
+| Memories are a flat pile of text | Knowledge graph with typed relationships (refines, cites, refuted_by, tags) |
+| Search results blow up your context window | Pre-computed summaries — search returns one-liners, fetch full content on demand |
+| No memory maintenance | Forage skill auto-consolidates, deduplicates, and connects |
+| Vector search requires heavy infra | Forage skill backfills embeddings using your existing AI subscription |
+| Requires Docker/Python/Cloud | `npx shelbymcp`, single SQLite file |
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+# npx (no install needed)
+npx shelbymcp
+
+# Or install globally
+npm install -g shelbymcp
+
+# Or build from source
+git clone https://github.com/Studio-Moser/shelbymcp.git
+cd shelbymcp
+npm install && npm run build
+```
+
+### Connect to Claude Code
+
+Add to your `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["shelbymcp", "--db", "~/.shelbymcp/memory.db"]
+    }
+  }
+}
+```
+
+### (Optional) Install the Forage Skill
+
+The Forage skill runs on Claude Code's scheduler to continuously improve your memories:
+
+```bash
+cp -r skills/shelby-forage ~/.claude/scheduled-tasks/shelby-forage
+```
+
+That's it. Your AI now remembers.
+
+---
+
+## How It Works
+
+```
+You (in Claude Code): "We decided to use CloudKit for sync instead of Firebase"
+
+Claude Code → capture_thought tool → ShelbyMCP:
+  1. Stores thought in SQLite
+  2. Agent provides metadata (type: decision, topics: [sync, cloud])
+  3. Agent suggests relationships to existing thoughts
+  4. FTS5 indexes content for keyword search
+
+Later:
+You: "What did we decide about our sync strategy?"
+
+Claude Code → search_thoughts tool → ShelbyMCP:
+  1. FTS5 keyword search for "sync strategy"
+  2. Returns thought + all connected thoughts via knowledge graph
+  3. Agent has full context of decisions, alternatives considered, and related work
+```
+
+### With the Forage Skill (scheduled, daily):
+
+```
+Forage runs on Claude Code's scheduler:
+  1. Backfills embeddings for thoughts that don't have them
+  2. Re-classifies poorly tagged thoughts
+  3. Finds duplicate thoughts and merges them
+  4. Detects contradictions ("we said PostgreSQL last month but SQLite this week")
+  5. Discovers connections between thoughts across projects
+  6. Sweeps for stale action items that fell through the cracks
+  7. Generates a weekly digest of your thinking
+```
+
+---
+
+## MCP Tools
+
+9 focused tools — research shows 5-8 tools per server is the sweet spot for agent accuracy.
+
+| Tool | Description |
+|---|---|
+| `capture_thought` | Store a thought with summary, metadata, topics, and relationships. Accepts an array for bulk capture. |
+| `search_thoughts` | Full-text search with knowledge graph expansion. Auto-detects FTS5 vs. vector mode. Returns summaries, not full content. |
+| `list_thoughts` | Browse/filter by type, topic, person, project, date range |
+| `get_thought` | Retrieve a specific thought by ID (full content) |
+| `update_thought` | Update content or metadata. Accepts `ids` array for bulk updates. |
+| `delete_thought` | Remove a thought |
+| `manage_edges` | Create or remove typed relationships between thoughts (link, unlink) |
+| `explore_graph` | Traverse the knowledge graph from a starting thought. Depth 1 = direct connections, 2+ = full traversal. |
+| `thought_stats` | Aggregate statistics about your memory |
+
+---
+
+## Knowledge Graph
+
+What makes ShelbyMCP different from every other memory server is the knowledge graph. Thoughts aren't isolated — they're connected.
+
+### Edge Types
+
+| Edge Type | Meaning | Example |
+|---|---|---|
+| `refines` | A thought that adds detail to another | "Use CloudKit" → "Configure change tokens for sync" |
+| `cites` | A thought that references another as evidence | "Decision doc" → "Performance benchmark results" |
+| `refuted_by` | A thought that contradicts another | "Use Firebase" ← "Switch to CloudKit" |
+| `tags` | A thought that categorizes another | "Architecture" → "CloudKit sync design" |
+| `related` | General association | "Auth system" ↔ "User migration plan" |
+| `follows` | Sequential relationship | "Phase 1 plan" → "Phase 2 plan" |
+
+Agents create edges at capture time ("this decision relates to thought X") and the Forage skill discovers additional connections over time.
+
+---
+
+## The Forage Skill
+
+ShelbyMCP ships with `shelby-forage`, a scheduled skill that runs on your existing AI subscription (Claude Code, Codex, etc.) to continuously improve your memory. The server stays zero-dependency — the intelligence comes from tools you're already paying for.
+
+| Task | Frequency | What it does |
+|---|---|---|
+| **Embed backfill** | Daily | Generate embeddings for thoughts that don't have them |
+| **Auto-classify** | Daily | Re-scan poorly tagged thoughts, improve metadata |
+| **Consolidation** | Daily | Find duplicate/similar thoughts, merge into rich summaries |
+| **Contradiction detection** | Daily | Flag conflicting memories for user resolution |
+| **Connection discovery** | Daily | Find related thoughts, create knowledge graph edges |
+| **Stale sweep** | Weekly | Flag old action items that fell through the cracks |
+| **Digest** | Weekly | Generate a summary of the week's thinking |
+
+### Install
+
+```bash
+cp -r skills/shelby-forage ~/.claude/scheduled-tasks/shelby-forage
+```
+
+The skill runs daily by default. Edit the SKILL.md frontmatter to adjust the schedule.
+
+### Without the Forage Skill
+
+ShelbyMCP works fine without it — you get persistent storage, FTS5 search, and knowledge graph. The Forage skill adds the intelligence layer that makes memories smarter over time. Think of it as optional but recommended.
+
+---
+
+## Agent Setup
+
+ShelbyMCP works with any MCP-compatible AI tool. See [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md) for setup guides:
+
+- Claude Code
+- Cursor
+- Codex
+- Windsurf
+- Gemini CLI
+- OpenCode
+- Any MCP-compatible client
+
+---
+
+## Architecture
+
+ShelbyMCP is a single binary that communicates via MCP (stdio JSON-RPC) and stores everything in a single SQLite file.
+
+```
+AI Tool (Claude Code, Cursor, etc.)
+    │
+    │ MCP (stdio JSON-RPC)
+    │
+    ▼
+┌──────────────────────┐
+│      ShelbyMCP        │
+│                        │
+│  ┌──────────────────┐ │
+│  │   MCP Protocol    │ │  ← JSON-RPC request/response
+│  │   (stdio)         │ │
+│  └────────┬─────────┘ │
+│           │            │
+│  ┌────────▼─────────┐ │
+│  │   Tool Router    │ │  ← Routes to capture/search/link/etc.
+│  └────────┬─────────┘ │
+│           │            │
+│  ┌────────▼─────────┐ │
+│  │    SQLite DB      │ │
+│  │  ┌─────────────┐ │ │
+│  │  │  thoughts    │ │ │  ← Content, metadata, embeddings
+│  │  │  thought_fts │ │ │  ← FTS5 full-text index
+│  │  │  edges       │ │ │  ← Knowledge graph relationships
+│  │  └─────────────┘ │ │
+│  └──────────────────┘ │
+└──────────────────────┘
+         │
+         ▼
+    ~/.shelbymcp/memory.db  (single file)
+```
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full technical design.
+
+---
+
+## Comparison
+
+| | ShelbyMCP | Engram | Mem0 | Basic Memory | Cipher |
+|---|---|---|---|---|---|
+| **Dependencies** | Zero | Zero | Docker+Qdrant+Neo4j | Python+pip | Node.js |
+| **Storage** | SQLite | SQLite | Qdrant+Neo4j+SQLite | Markdown+SQLite | Files |
+| **Knowledge graph** | Native (typed edges) | No | Neo4j (separate service) | Derived from Markdown | No |
+| **Full-text search** | FTS5 | FTS5 | Limited | FTS5 | No |
+| **Vector search** | Via Forage skill | No | Built-in | Optional | No |
+| **Memory maintenance** | Forage skill (daily) | No | Built-in | No | No |
+| **Contradiction detection** | Forage skill | No | No | No | No |
+| **Zero-install** | `npx shelbymcp` | `go install` | No | `pip install` | `npm install` |
+| **Single file DB** | Yes | Yes | No | No (Markdown files) | No |
+
+---
+
+## Part of the Shelby Ecosystem
+
+ShelbyMCP is the open-source memory server. **Shelby for Mac** (coming soon) is the native macOS app that adds:
+
+- Always-on embedding pipeline (no scheduled skill needed)
+- Instant auto-classification at capture time
+- Semantic vector search
+- CloudKit sync across all your Macs
+- Heartbeat system (Pulse / Tidyup / Forage)
+- Native menu bar + global hotkey quick capture
+- Extension discovery and management
+
+ShelbyMCP and Shelby for Mac use the same SQLite database. Start with the MCP server, upgrade to the Mac app when you want more.
+
+---
+
+## Design Principles for Contributors
+
+These are non-negotiable. They exist because MCP servers directly impact token costs for every user on every message.
+
+1. **Tool descriptions MUST be static.** Tool definitions become part of the agent's system prompt and are sent on every message. Dynamic data (counts, timestamps, user-specific info) in descriptions breaks prompt caching — costing 10x more tokens. Put dynamic data in tool *responses*, not descriptions. See [Architecture: Token Efficiency Patterns](docs/ARCHITECTURE.md#token-efficiency-patterns).
+
+2. **Search returns summaries, not full content.** A search hitting 20 thoughts at 2,000 words each = 40K wasted tokens. Search results return the agent-provided `summary` field (one line). The agent calls `get_thought` for full content when it needs it.
+
+3. **All list/search tools have a `limit` parameter.** Default 20, max 100. Responses include `total_count` and `has_more`. No unbounded queries.
+
+4. **The server runs zero inference.** Agents provide metadata (type, topics, summary, relationships) at capture time. The Forage skill handles enrichment. The server is pure storage + retrieval.
+
+5. **All logging to stderr.** `console.error` only. stdout is the MCP JSON-RPC channel. A single `console.log` breaks everything.
+
+6. **Keep the tool count focused.** 9 tools. Research (Block, Phil Schmid, Docker) shows 5-8 per server is optimal. Consolidate related operations into single tools with action parameters.
+
+7. **Errors are instructions.** Return `isError: true` with actionable messages. "Not found" is useless. "No thought with ID abc123. Try search_thoughts to find it by content." helps the agent self-correct.
+
+8. **Every tool gets annotations.** MCP spec annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) on every registered tool. See [Architecture: Tool Annotations](docs/ARCHITECTURE.md#tool-annotations).
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run in development
+npm run dev -- --db ./test.db --verbose
+```
+
+See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for the full development guide.
+
+---
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow.
+
+- **Issues first** — Open an issue before starting work
+- **PRs welcome** — Bug fixes, new MCP tools, documentation improvements
+- **Forage tasks** — Propose new Forage skill tasks for memory enrichment
+
+---
+
+## License
+
+MIT - see [LICENSE](LICENSE) for details.
+
+---
+
+<p align="center">
+  <sub>Built by <a href="https://github.com/Studio-Moser">Studio Moser</a>. Your AI deserves a memory that connects the dots.</sub>
+</p>

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+export interface ShelbyConfig {
+    dbPath: string;
+    verbose: boolean;
+    logFile: string | null;
+}
+export declare function parseArgs(argv: string[]): ShelbyConfig | "version";
+export declare function getDefaultDbPath(): string;
+export declare function getDefaultDbDir(): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAKD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,SAAS,CAyBlE;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,wBAAgB,eAAe,IAAI,MAAM,CAExC"}

package/dist/config.js

@@ -0,0 +1,35 @@
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+const DEFAULT_DB_DIR = resolve(homedir(), ".shelbymcp");
+const DEFAULT_DB_PATH = resolve(DEFAULT_DB_DIR, "memory.db");
+export function parseArgs(argv) {
+    const config = {
+        dbPath: DEFAULT_DB_PATH,
+        verbose: false,
+        logFile: null,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--db":
+                config.dbPath = resolve(argv[++i] ?? DEFAULT_DB_PATH);
+                break;
+            case "--verbose":
+                config.verbose = true;
+                break;
+            case "--log-file":
+                config.logFile = resolve(argv[++i] ?? "");
+                break;
+            case "--version":
+                return "version";
+        }
+    }
+    return config;
+}
+export function getDefaultDbPath() {
+    return DEFAULT_DB_PATH;
+}
+export function getDefaultDbDir() {
+    return DEFAULT_DB_DIR;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAQlC,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,EAAE,EAAE,YAAY,CAAC,CAAC;AACxD,MAAM,eAAe,GAAG,OAAO,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;AAE7D,MAAM,UAAU,SAAS,CAAC,IAAc;IACtC,MAAM,MAAM,GAAiB;QAC3B,MAAM,EAAE,eAAe;QACvB,OAAO,EAAE,KAAK;QACd,OAAO,EAAE,IAAI;KACd,CAAC;IAEF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,QAAQ,GAAG,EAAE,CAAC;YACZ,KAAK,MAAM;gBACT,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC;gBACtD,MAAM;YACR,KAAK,WAAW;gBACd,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;gBACtB,MAAM;YACR,KAAK,YAAY;gBACf,MAAM,CAAC,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;gBAC1C,MAAM;YACR,KAAK,WAAW;gBACd,OAAO,SAAS,CAAC;QACrB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO,cAAc,CAAC;AACxB,CAAC"}

package/dist/db/database.d.ts

@@ -0,0 +1,8 @@
+import Database from "better-sqlite3";
+export declare class ThoughtDatabase {
+    readonly db: Database.Database;
+    constructor(dbPath: string);
+    getSchemaVersion(): number;
+    close(): void;
+}
+//# sourceMappingURL=database.d.ts.map

package/dist/db/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/db/database.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAKtC,qBAAa,eAAe;IAC1B,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,CAAC;gBAEnB,MAAM,EAAE,MAAM;IAc1B,gBAAgB,IAAI,MAAM;IAI1B,KAAK,IAAI,IAAI;CAGd"}

package/dist/db/database.js

@@ -0,0 +1,25 @@
+import Database from "better-sqlite3";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { runMigrations, getSchemaVersion } from "./migrations.js";
+export class ThoughtDatabase {
+    db;
+    constructor(dbPath) {
+        if (dbPath !== ":memory:") {
+            mkdirSync(dirname(dbPath), { recursive: true });
+        }
+        this.db = new Database(dbPath);
+        if (dbPath !== ":memory:") {
+            this.db.pragma("journal_mode = WAL");
+        }
+        this.db.pragma("foreign_keys = ON");
+        runMigrations(this.db);
+    }
+    getSchemaVersion() {
+        return getSchemaVersion(this.db);
+    }
+    close() {
+        this.db.close();
+    }
+}
+//# sourceMappingURL=database.js.map

package/dist/db/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../src/db/database.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAElE,MAAM,OAAO,eAAe;IACjB,EAAE,CAAoB;IAE/B,YAAY,MAAc;QACxB,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;YAC1B,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,CAAC;QAED,IAAI,CAAC,EAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;YAC1B,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;QACvC,CAAC;QACD,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;QAEpC,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACzB,CAAC;IAED,gBAAgB;QACd,OAAO,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;CACF"}

package/dist/db/edges.d.ts

@@ -0,0 +1,65 @@
+import type { ThoughtDatabase } from "./database.js";
+export declare const VALID_EDGE_TYPES: readonly ["refines", "cites", "refuted_by", "tags", "related", "follows"];
+export type EdgeType = (typeof VALID_EDGE_TYPES)[number];
+export interface EdgeInput {
+    source_id: string;
+    target_id: string;
+    edge_type: string;
+    metadata?: Record<string, unknown>;
+}
+export interface EdgeRecord {
+    id: string;
+    source_id: string;
+    target_id: string;
+    edge_type: string;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+}
+export interface ConnectedThought {
+    thought_id: string;
+    summary: string | null;
+    type: string;
+    edge_id: string;
+    edge_type: string;
+    direction: "outgoing" | "incoming";
+}
+export interface GraphNode {
+    id: string;
+    summary: string | null;
+    type: string;
+    depth: number;
+    edges: Array<{
+        edge_id: string;
+        edge_type: string;
+        connected_to: string;
+        direction: "outgoing" | "incoming";
+    }>;
+}
+/**
+ * Create an edge between two thoughts. Returns the new edge's UUID.
+ * Throws if source or target don't exist, or if a duplicate edge exists.
+ */
+export declare function linkThoughts(db: ThoughtDatabase, input: EdgeInput): string;
+/**
+ * Remove an edge between two thoughts. Returns true if an edge was deleted.
+ */
+export declare function unlinkThoughts(db: ThoughtDatabase, source_id: string, target_id: string, edge_type: string): boolean;
+/**
+ * Get a single edge by ID.
+ */
+export declare function getEdge(db: ThoughtDatabase, id: string): EdgeRecord | null;
+/**
+ * Get all edges between two specific thoughts (any type).
+ */
+export declare function getEdgesBetween(db: ThoughtDatabase, source_id: string, target_id: string): EdgeRecord[];
+/**
+ * Get direct connections for a thought (both outgoing and incoming).
+ * Optionally filter by edge types.
+ */
+export declare function getConnections(db: ThoughtDatabase, thought_id: string, edge_types?: string[]): ConnectedThought[];
+/**
+ * BFS traversal from a starting thought up to max_depth (capped at 5).
+ * Returns all discovered nodes with their depth and edges.
+ */
+export declare function traverseGraph(db: ThoughtDatabase, thought_id: string, max_depth: number, edge_types?: string[]): GraphNode[];
+//# sourceMappingURL=edges.d.ts.map

package/dist/db/edges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edges.d.ts","sourceRoot":"","sources":["../../src/db/edges.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAIrD,eAAO,MAAM,gBAAgB,2EAOnB,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC;CACpC;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,KAAK,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC;KACpC,CAAC,CAAC;CACJ;AA0BD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,CA8C1E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,eAAe,EACnB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAQT;AAED;;GAEG;AACH,wBAAgB,OAAO,CACrB,EAAE,EAAE,eAAe,EACnB,EAAE,EAAE,MAAM,GACT,UAAU,GAAG,IAAI,CAMnB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,eAAe,EACnB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,UAAU,EAAE,CAQd;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,EAAE,GACpB,gBAAgB,EAAE,CAuDpB;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,MAAM,EAAE,GACpB,SAAS,EAAE,CAwHb"}