@a13xu/lucid 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 a13xu
+
+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,99 @@
+# @a13xu/lucid
+
+Persistent memory for Claude Code agents, backed by **SQLite + FTS5**.
+
+Stores a knowledge graph (entities, relations, observations) with full-text search — indexed queries under 1ms, no JSON files, no linear scans.
+
+## Install
+
+**Requirements:** Node.js 18+
+
+```bash
+# Run directly (no install needed)
+npx @a13xu/lucid
+
+# Or install globally
+npm install -g @a13xu/lucid
+lucid
+```
+
+### Add to Claude Code
+
+```bash
+claude mcp add --transport stdio lucid -- npx -y @a13xu/lucid
+```
+
+Or add manually to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "lucid": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@a13xu/lucid"],
+      "env": {
+        "MEMORY_DB_PATH": "/your/project/.claude/memory.db"
+      }
+    }
+  }
+}
+```
+
+Default DB path: `~/.claude/memory.db`
+
+## Why SQLite + FTS5 instead of JSON?
+
+| | JSON file | SQLite + FTS5 |
+|---|---|---|
+| Search | O(n) linear scan | O(log n) indexed |
+| Write | Rewrite entire file | Atomic incremental |
+| Concurrent reads | Lock entire file | WAL mode |
+| Stemming / unicode | Manual | Built-in |
+
+## Tools (6)
+
+| Tool | Description |
+|---|---|
+| `remember` | Store a fact about an entity (project, person, tool, decision…) |
+| `relate` | Create a directed relationship between two entities |
+| `recall` | Full-text search across all memory (FTS5 + LIKE fallback) |
+| `recall_all` | Return the entire knowledge graph with stats |
+| `forget` | Remove an entity and all its relations |
+| `memory_stats` | DB size, WAL status, entity/relation counts |
+
+### Entity types
+`person` · `project` · `decision` · `pattern` · `tool` · `config` · `bug` · `convention`
+
+### Relation types
+`uses` · `depends_on` · `created_by` · `part_of` · `replaced_by` · `conflicts_with` · `tested_by`
+
+## Usage examples
+
+```
+You:    "Remember that this project uses PostgreSQL with Prisma ORM"
+Claude: [calls remember] → Created "PostgreSQL" [tool]
+
+You:    "What do you know about the database?"
+Claude: [calls recall("database PostgreSQL")] → returns entity + observations
+
+You:    "How are the services connected?"
+Claude: [calls recall_all] → returns full knowledge graph
+```
+
+## Debugging
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{},"clientInfo":{"name":"test","version":"1.0"},"protocolVersion":"2024-11-05"}}' \
+  | npx @a13xu/lucid
+```
+
+In Claude Code: run `/mcp` — you should see `lucid` listed with 6 tools.
+
+## Tech stack
+
+- **Runtime:** Node.js 18+, TypeScript, ES modules
+- **MCP SDK:** `@modelcontextprotocol/sdk`
+- **Database:** `better-sqlite3` (synchronous, no async overhead)
+- **Validation:** `zod`
+- **Transport:** stdio

package/build/database.d.ts

@@ -0,0 +1,34 @@
+import Database from "better-sqlite3";
+import type { EntityRow, RelationRow } from "./types.js";
+export declare function initDatabase(): Database.Database;
+type Stmt<P extends unknown[], R> = Database.Statement<P, R>;
+type WriteStmt<P extends unknown[]> = Database.Statement<P, unknown>;
+export interface Statements {
+    getEntityByName: Stmt<[string], EntityRow>;
+    insertEntity: WriteStmt<[string, string, string]>;
+    updateEntity: WriteStmt<[string, number]>;
+    deleteEntity: WriteStmt<[string]>;
+    getAllEntities: Stmt<[], EntityRow>;
+    getRelationsForEntity: Stmt<[number, number], RelationRow & {
+        from_name: string;
+        to_name: string;
+    }>;
+    insertRelation: WriteStmt<[number, number, string]>;
+    searchFTS: Stmt<[string], EntityRow>;
+    searchLike: Stmt<[string, string, string], EntityRow>;
+    countEntities: Stmt<[], {
+        count: number;
+    }>;
+    countRelations: Stmt<[], {
+        count: number;
+    }>;
+    getWalMode: Stmt<[], {
+        journal_mode: string;
+    }>;
+    getAllRelations: Stmt<[], RelationRow & {
+        from_name: string;
+        to_name: string;
+    }>;
+}
+export declare function prepareStatements(db: Database.Database): Statements;
+export {};

package/build/database.js

@@ -0,0 +1,114 @@
+import Database from "better-sqlite3";
+import { homedir } from "os";
+import { mkdirSync } from "fs";
+import { dirname, join } from "path";
+// ---------------------------------------------------------------------------
+// DB path
+// ---------------------------------------------------------------------------
+function resolveDbPath() {
+    const envPath = process.env["MEMORY_DB_PATH"];
+    if (envPath)
+        return envPath;
+    return join(homedir(), ".claude", "memory.db");
+}
+// ---------------------------------------------------------------------------
+// Init
+// ---------------------------------------------------------------------------
+export function initDatabase() {
+    const dbPath = resolveDbPath();
+    mkdirSync(dirname(dbPath), { recursive: true });
+    const db = new Database(dbPath);
+    // Pragmas obligatorii
+    db.pragma("journal_mode = WAL");
+    db.pragma("synchronous = NORMAL");
+    db.pragma("cache_size = -8000");
+    db.pragma("temp_store = MEMORY");
+    db.pragma("mmap_size = 67108864");
+    db.pragma("foreign_keys = ON");
+    createSchema(db);
+    console.error(`[lucid] DB: ${dbPath}`);
+    return db;
+}
+function createSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS entities (
+      id           INTEGER PRIMARY KEY,
+      name         TEXT NOT NULL UNIQUE COLLATE NOCASE,
+      type         TEXT NOT NULL,
+      observations TEXT NOT NULL DEFAULT '[]',
+      created_at   INTEGER DEFAULT (unixepoch()),
+      updated_at   INTEGER DEFAULT (unixepoch())
+    );
+
+    CREATE TABLE IF NOT EXISTS relations (
+      id            INTEGER PRIMARY KEY,
+      from_entity   INTEGER NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
+      to_entity     INTEGER NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
+      relation_type TEXT NOT NULL,
+      created_at    INTEGER DEFAULT (unixepoch()),
+      UNIQUE(from_entity, to_entity, relation_type)
+    );
+
+    CREATE VIRTUAL TABLE IF NOT EXISTS entities_fts USING fts5(
+      name,
+      type,
+      observations,
+      content='entities',
+      content_rowid='id',
+      tokenize='porter unicode61'
+    );
+
+    CREATE TRIGGER IF NOT EXISTS entities_ai AFTER INSERT ON entities BEGIN
+      INSERT INTO entities_fts(rowid, name, type, observations)
+      VALUES (new.id, new.name, new.type, new.observations);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS entities_au AFTER UPDATE ON entities BEGIN
+      INSERT INTO entities_fts(entities_fts, rowid, name, type, observations)
+      VALUES('delete', old.id, old.name, old.type, old.observations);
+      INSERT INTO entities_fts(rowid, name, type, observations)
+      VALUES (new.id, new.name, new.type, new.observations);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS entities_ad AFTER DELETE ON entities BEGIN
+      INSERT INTO entities_fts(entities_fts, rowid, name, type, observations)
+      VALUES('delete', old.id, old.name, old.type, old.observations);
+    END;
+
+    CREATE INDEX IF NOT EXISTS idx_relations_from ON relations(from_entity);
+    CREATE INDEX IF NOT EXISTS idx_relations_to   ON relations(to_entity);
+    CREATE INDEX IF NOT EXISTS idx_entities_type  ON entities(type);
+  `);
+}
+export function prepareStatements(db) {
+    return {
+        getEntityByName: db.prepare("SELECT * FROM entities WHERE name = ? COLLATE NOCASE"),
+        insertEntity: db.prepare("INSERT INTO entities (name, type, observations) VALUES (?, ?, ?)"),
+        // SQL: SET observations = ?, WHERE id = ?  →  2 params
+        updateEntity: db.prepare("UPDATE entities SET observations = ?, updated_at = unixepoch() WHERE id = ?"),
+        deleteEntity: db.prepare("DELETE FROM entities WHERE name = ? COLLATE NOCASE"),
+        getAllEntities: db.prepare("SELECT * FROM entities ORDER BY updated_at DESC"),
+        getRelationsForEntity: db.prepare(`SELECT r.*, ef.name AS from_name, et.name AS to_name
+       FROM relations r
+       JOIN entities ef ON r.from_entity = ef.id
+       JOIN entities et ON r.to_entity = et.id
+       WHERE r.from_entity = ? OR r.to_entity = ?`),
+        insertRelation: db.prepare("INSERT OR IGNORE INTO relations (from_entity, to_entity, relation_type) VALUES (?, ?, ?)"),
+        searchFTS: db.prepare(`SELECT e.* FROM entities_fts
+       JOIN entities e ON entities_fts.rowid = e.id
+       WHERE entities_fts MATCH ?
+       ORDER BY rank
+       LIMIT 20`),
+        searchLike: db.prepare(`SELECT * FROM entities
+       WHERE name LIKE ? OR type LIKE ? OR observations LIKE ?
+       ORDER BY updated_at DESC
+       LIMIT 20`),
+        countEntities: db.prepare("SELECT COUNT(*) as count FROM entities"),
+        countRelations: db.prepare("SELECT COUNT(*) as count FROM relations"),
+        getWalMode: db.prepare("PRAGMA journal_mode"),
+        getAllRelations: db.prepare(`SELECT r.*, ef.name AS from_name, et.name AS to_name
+       FROM relations r
+       JOIN entities ef ON r.from_entity = ef.id
+       JOIN entities et ON r.to_entity = et.id`),
+    };
+}

package/build/index.d.ts

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

package/build/index.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { initDatabase, prepareStatements } from "./database.js";
+import { remember, RememberSchema } from "./tools/remember.js";
+import { relate, RelateSchema } from "./tools/relate.js";
+import { recall, RecallSchema } from "./tools/recall.js";
+import { recallAll } from "./tools/recall-all.js";
+import { forget, ForgetSchema } from "./tools/forget.js";
+import { memoryStats } from "./tools/stats.js";
+// ---------------------------------------------------------------------------
+// Init DB
+// ---------------------------------------------------------------------------
+const db = initDatabase();
+const stmts = prepareStatements(db);
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+const server = new Server({ name: "lucid", version: "1.0.0" }, { capabilities: { tools: {} } });
+// ---------------------------------------------------------------------------
+// Tool definitions
+// ---------------------------------------------------------------------------
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "remember",
+            description: "Store a fact, decision, or observation about an entity in the knowledge graph.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    entity: { type: "string", description: "Entity name (project, person, concept, tool)" },
+                    entityType: {
+                        type: "string",
+                        enum: ["person", "project", "decision", "pattern", "tool", "config", "bug", "convention"],
+                    },
+                    observation: { type: "string", description: "The fact to remember" },
+                },
+                required: ["entity", "entityType", "observation"],
+            },
+        },
+        {
+            name: "relate",
+            description: "Create a directed relationship between two entities in the knowledge graph.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    from: { type: "string", description: "Source entity name" },
+                    to: { type: "string", description: "Target entity name" },
+                    relationType: {
+                        type: "string",
+                        enum: ["uses", "depends_on", "created_by", "part_of", "replaced_by", "conflicts_with", "tested_by"],
+                    },
+                },
+                required: ["from", "to", "relationType"],
+            },
+        },
+        {
+            name: "recall",
+            description: "Search memory using full-text search. Fast, indexed, supports partial matches and stemming.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Search terms" },
+                },
+                required: ["query"],
+            },
+        },
+        {
+            name: "recall_all",
+            description: "Get the entire knowledge graph with statistics.",
+            inputSchema: { type: "object", properties: {} },
+        },
+        {
+            name: "forget",
+            description: "Remove an entity and all its relations from memory.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    entity: { type: "string", description: "Entity name to remove" },
+                },
+                required: ["entity"],
+            },
+        },
+        {
+            name: "memory_stats",
+            description: "Get memory usage statistics.",
+            inputSchema: { type: "object", properties: {} },
+        },
+    ],
+}));
+// ---------------------------------------------------------------------------
+// Tool handlers
+// ---------------------------------------------------------------------------
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        let text;
+        switch (name) {
+            case "remember": {
+                const input = RememberSchema.parse(args);
+                text = remember(stmts, input);
+                break;
+            }
+            case "relate": {
+                const input = RelateSchema.parse(args);
+                text = relate(stmts, input);
+                break;
+            }
+            case "recall": {
+                const input = RecallSchema.parse(args);
+                text = recall(stmts, input);
+                break;
+            }
+            case "recall_all": {
+                text = recallAll(db, stmts);
+                break;
+            }
+            case "forget": {
+                const input = ForgetSchema.parse(args);
+                text = forget(stmts, input);
+                break;
+            }
+            case "memory_stats": {
+                text = memoryStats(db, stmts);
+                break;
+            }
+            default:
+                return {
+                    content: [{ type: "text", text: `Unknown tool: ${name}` }],
+                    isError: true,
+                };
+        }
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        const message = err instanceof z.ZodError
+            ? `Validation error: ${err.errors.map((e) => e.message).join(", ")}`
+            : err instanceof Error
+                ? err.message
+                : String(err);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("[lucid] Server started on stdio.");

package/build/tools/forget.d.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import type { Statements } from "../database.js";
+export declare const ForgetSchema: z.ZodObject<{
+    entity: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    entity: string;
+}, {
+    entity: string;
+}>;
+export type ForgetInput = z.infer<typeof ForgetSchema>;
+export declare function forget(stmts: Statements, input: ForgetInput): string;

package/build/tools/forget.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+export const ForgetSchema = z.object({
+    entity: z.string().min(1),
+});
+export function forget(stmts, input) {
+    const existing = stmts.getEntityByName.get(input.entity);
+    if (!existing) {
+        return `Entity "${input.entity}" not found in memory.`;
+    }
+    // ON DELETE CASCADE șterge relațiile automat
+    stmts.deleteEntity.run(input.entity);
+    return `Removed "${input.entity}" and all its relations from memory.`;
+}

package/build/tools/recall-all.d.ts

@@ -0,0 +1,3 @@
+import Database from "better-sqlite3";
+import type { Statements } from "../database.js";
+export declare function recallAll(db: Database.Database, stmts: Statements): string;

package/build/tools/recall-all.js

@@ -0,0 +1,45 @@
+import { statSync } from "fs";
+export function recallAll(db, stmts) {
+    const entityCount = stmts.countEntities.get().count;
+    const relationCount = stmts.countRelations.get().count;
+    const allEntities = stmts.getAllEntities.all();
+    const allRelations = stmts.getAllRelations.all();
+    // Numără toate observațiile
+    let observationCount = 0;
+    const entities = allEntities.map((row) => {
+        const observations = JSON.parse(row.observations);
+        observationCount += observations.length;
+        const relations = allRelations
+            .filter((r) => r.from_entity === row.id || r.to_entity === row.id)
+            .map((r) => ({ from: r.from_name, to: r.to_name, type: r.relation_type }));
+        return {
+            id: row.id,
+            name: row.name,
+            type: row.type,
+            observations,
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+            relations,
+        };
+    });
+    let dbSizeBytes = 0;
+    try {
+        dbSizeBytes = statSync(db.name).size;
+    }
+    catch {
+        // fișierul poate fi in-memory sau inaccesibil
+    }
+    const graph = {
+        stats: {
+            entity_count: entityCount,
+            relation_count: relationCount,
+            observation_count: observationCount,
+            db_size_bytes: dbSizeBytes,
+            db_size_kb: Math.round(dbSizeBytes / 1024),
+            wal_mode: true,
+            fts5_enabled: true,
+        },
+        entities,
+    };
+    return JSON.stringify(graph, null, 2);
+}

package/build/tools/recall.d.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import type { Statements } from "../database.js";
+export declare const RecallSchema: z.ZodObject<{
+    query: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+}, {
+    query: string;
+}>;
+export type RecallInput = z.infer<typeof RecallSchema>;
+export declare function recall(stmts: Statements, input: RecallInput): string;

package/build/tools/recall.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+export const RecallSchema = z.object({
+    query: z.string().min(1),
+});
+function sanitizeFTSQuery(query) {
+    return query
+        .replace(/[^\w\s\u00C0-\u024F]/g, "") // păstrează litere + diacritice
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .join(" OR ");
+}
+function buildEntityWithRelations(stmts, row) {
+    const observations = JSON.parse(row.observations);
+    const relRows = stmts.getRelationsForEntity.all(row.id, row.id);
+    const relations = relRows.map((r) => ({
+        from: r.from_name,
+        to: r.to_name,
+        type: r.relation_type,
+    }));
+    return {
+        id: row.id,
+        name: row.name,
+        type: row.type,
+        observations,
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+        relations,
+    };
+}
+export function recall(stmts, input) {
+    const sanitized = sanitizeFTSQuery(input.query);
+    let rows = [];
+    if (sanitized) {
+        try {
+            rows = stmts.searchFTS.all(sanitized);
+        }
+        catch {
+            // FTS query invalid — fallback la LIKE
+            console.error(`[lucid] FTS fallback for query: ${sanitized}`);
+        }
+    }
+    // Fallback LIKE dacă FTS nu a returnat rezultate
+    if (rows.length === 0) {
+        const like = `%${input.query}%`;
+        rows = stmts.searchLike.all(like, like, like);
+    }
+    if (rows.length === 0) {
+        return `No results found for "${input.query}".`;
+    }
+    const entities = rows.map((row) => buildEntityWithRelations(stmts, row));
+    return JSON.stringify(entities, null, 2);
+}

package/build/tools/relate.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import type { Statements } from "../database.js";
+export declare const RelateSchema: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    relationType: z.ZodEnum<["uses", "depends_on", "created_by", "part_of", "replaced_by", "conflicts_with", "tested_by"]>;
+}, "strip", z.ZodTypeAny, {
+    from: string;
+    to: string;
+    relationType: "uses" | "depends_on" | "created_by" | "part_of" | "replaced_by" | "conflicts_with" | "tested_by";
+}, {
+    from: string;
+    to: string;
+    relationType: "uses" | "depends_on" | "created_by" | "part_of" | "replaced_by" | "conflicts_with" | "tested_by";
+}>;
+export type RelateInput = z.infer<typeof RelateSchema>;
+export declare function relate(stmts: Statements, input: RelateInput): string;

package/build/tools/relate.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+export const RelateSchema = z.object({
+    from: z.string().min(1),
+    to: z.string().min(1),
+    relationType: z.enum([
+        "uses", "depends_on", "created_by", "part_of",
+        "replaced_by", "conflicts_with", "tested_by",
+    ]),
+});
+export function relate(stmts, input) {
+    const fromEntity = stmts.getEntityByName.get(input.from);
+    if (!fromEntity) {
+        return `Error: Entity "${input.from}" not found. Use remember() to create it first.`;
+    }
+    const toEntity = stmts.getEntityByName.get(input.to);
+    if (!toEntity) {
+        return `Error: Entity "${input.to}" not found. Use remember() to create it first.`;
+    }
+    stmts.insertRelation.run(fromEntity.id, toEntity.id, input.relationType);
+    return `${input.from} --[${input.relationType}]--> ${input.to}`;
+}

package/build/tools/remember.d.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import type { Statements } from "../database.js";
+export declare const RememberSchema: z.ZodObject<{
+    entity: z.ZodString;
+    entityType: z.ZodEnum<["person", "project", "decision", "pattern", "tool", "config", "bug", "convention"]>;
+    observation: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    entity: string;
+    entityType: "person" | "project" | "decision" | "pattern" | "tool" | "config" | "bug" | "convention";
+    observation: string;
+}, {
+    entity: string;
+    entityType: "person" | "project" | "decision" | "pattern" | "tool" | "config" | "bug" | "convention";
+    observation: string;
+}>;
+export type RememberInput = z.infer<typeof RememberSchema>;
+export declare function remember(stmts: Statements, input: RememberInput): string;

package/build/tools/remember.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+export const RememberSchema = z.object({
+    entity: z.string().min(1),
+    entityType: z.enum([
+        "person", "project", "decision", "pattern",
+        "tool", "config", "bug", "convention",
+    ]),
+    observation: z.string().min(1),
+});
+export function remember(stmts, input) {
+    const { entity, entityType, observation } = input;
+    const existing = stmts.getEntityByName.get(entity);
+    if (existing) {
+        const observations = JSON.parse(existing.observations);
+        // Nu adăuga duplicate
+        if (!observations.includes(observation)) {
+            observations.push(observation);
+            stmts.updateEntity.run(JSON.stringify(observations), existing.id);
+        }
+        return `Updated "${entity}" [${existing.type}] — ${observations.length} observation(s) total.`;
+    }
+    else {
+        stmts.insertEntity.run(entity, entityType, JSON.stringify([observation]));
+        return `Created "${entity}" [${entityType}].`;
+    }
+}

package/build/tools/stats.d.ts

@@ -0,0 +1,3 @@
+import Database from "better-sqlite3";
+import type { Statements } from "../database.js";
+export declare function memoryStats(db: Database.Database, stmts: Statements): string;

package/build/tools/stats.js

@@ -0,0 +1,30 @@
+import { statSync } from "fs";
+export function memoryStats(db, stmts) {
+    const entityCount = stmts.countEntities.get().count;
+    const relationCount = stmts.countRelations.get().count;
+    const walMode = stmts.getWalMode.get().journal_mode === "wal";
+    // Numără observațiile
+    const allEntities = stmts.getAllEntities.all();
+    let observationCount = 0;
+    for (const row of allEntities) {
+        const obs = JSON.parse(row.observations);
+        observationCount += obs.length;
+    }
+    let dbSizeBytes = 0;
+    try {
+        dbSizeBytes = statSync(db.name).size;
+    }
+    catch {
+        // in-memory sau inaccesibil
+    }
+    const stats = {
+        entity_count: entityCount,
+        relation_count: relationCount,
+        observation_count: observationCount,
+        db_size_bytes: dbSizeBytes,
+        db_size_kb: Math.round(dbSizeBytes / 1024),
+        wal_mode: walMode,
+        fts5_enabled: true,
+    };
+    return JSON.stringify(stats, null, 2);
+}

package/build/types.d.ts

@@ -0,0 +1,53 @@
+export type EntityType = "person" | "project" | "decision" | "pattern" | "tool" | "config" | "bug" | "convention";
+export type RelationType = "uses" | "depends_on" | "created_by" | "part_of" | "replaced_by" | "conflicts_with" | "tested_by";
+export interface Entity {
+    id: number;
+    name: string;
+    type: EntityType;
+    observations: string[];
+    created_at: number;
+    updated_at: number;
+}
+export interface EntityRow {
+    id: number;
+    name: string;
+    type: string;
+    observations: string;
+    created_at: number;
+    updated_at: number;
+}
+export interface Relation {
+    id: number;
+    from_entity: number;
+    to_entity: number;
+    relation_type: RelationType;
+    created_at: number;
+}
+export interface RelationRow {
+    id: number;
+    from_entity: number;
+    to_entity: number;
+    relation_type: string;
+    created_at: number;
+}
+export interface EntityWithRelations extends Entity {
+    relations: RelationDisplay[];
+}
+export interface RelationDisplay {
+    from: string;
+    to: string;
+    type: string;
+}
+export interface MemoryStats {
+    entity_count: number;
+    relation_count: number;
+    observation_count: number;
+    db_size_bytes: number;
+    db_size_kb: number;
+    wal_mode: boolean;
+    fts5_enabled: boolean;
+}
+export interface KnowledgeGraph {
+    stats: MemoryStats;
+    entities: EntityWithRelations[];
+}

package/build/types.js

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

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@a13xu/lucid",
+  "version": "1.0.0",
+  "description": "Persistent memory for Claude Code agents — SQLite + FTS5 knowledge graph via MCP",
+  "type": "module",
+  "bin": {
+    "lucid": "./build/index.js"
+  },
+  "files": [
+    "build/**/*.js",
+    "build/**/*.d.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "claude-code",
+    "memory",
+    "sqlite",
+    "knowledge-graph",
+    "ai",
+    "anthropic"
+  ],
+  "author": "a13xu",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/a13xu/lucid.git"
+  },
+  "homepage": "https://github.com/a13xu/lucid#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^11.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}