@postnesia/db 0.1.6 → 0.1.7

package/core/BOOTSTRAP.md

@@ -25,6 +25,8 @@ If an MCP connection to `postnesia-mcp` is active, use MCP tools directly:
 | `memory_stats` | Check database health and distribution. |
 | `memory_consolidate` | Run decay/boost cycle on importance scores. |
 | `memory_relationships` | Explore how a memory connects to others. |
+| `memory_link` | Manually create a typed relationship between two memories. |
+| `memory_unlink` | Remove a relationship by its ID. |
 | `journal_add` | Write a daily journal entry (narrative). |
 | `journal_recent` | Read recent journal entries. |
 | `task_create` | Create a persistent task with an optional `session_id` to group by project/feature. |
@@ -44,6 +46,8 @@ If no MCP connection is available, use the `postnesia` CLI via Bash. Every MCP t
 | `memory_stats` | `postnesia memory stats` |
 | `memory_consolidate` | `postnesia memory consolidate` |
 | `memory_relationships` | `postnesia memory relationships <id>` |
+| `memory_link` | `postnesia memory link <fromId> <toId> --type <type>` |
+| `memory_unlink` | `postnesia memory unlink <relationshipId>` |
 | `journal_add` | `postnesia journal add <YYYY-MM-DD> "<content>" [--learned "..."] [--key-moments "..."] [--mood "..."]` |
 | `journal_recent` | `postnesia journal recent [--days N]` |
 | `task_create` | `postnesia task create "<title>" [-d "<description>"] [-s <session-id>]` |
@@ -135,11 +139,31 @@ Memories you access frequently stay in L1 forever. Memories not accessed in 14+
 
 Tag liberally at creation time. Tags improve both keyword filtering and search relevance. Use lowercase, hyphenated: `memory-system`, `rye-preference`, `critical-thinking`.
 
+## Relationships
+
+Memories form a knowledge graph via typed edges. Relationships are used by `memory_consolidate` to boost the importance of well-connected memories.
+
+### Auto-linking (happens automatically on `memory_add`)
+
+- **`related`** — inserted for any existing memory within vector distance 0.4 of the new memory
+- **`supersedes`** — inserted when `supersedes_id` is provided
+
+### Manual link types
+
+| Type | When to use |
+|---|---|
+| `supports` | This memory provides evidence or context for another |
+| `contradicts` | This memory conflicts with or overrides another |
+| `derives_from` | This memory was derived from, inspired by, or builds on another |
+
+Use `memory_link` to assert these explicitly. Use `memory_relationships` to inspect the graph before deciding how a new memory relates to existing ones.
+
 ## Critical Rules
 
 1. **Search before assuming.** If you're unsure about a preference, decision, or past event — search for it.
 2. **Store decisions in real time.** Don't wait until end of session. If a user makes a meaningful choice, store it now.
 3. **Never store noise.** Quality over quantity. Every memory costs tokens in L1.
 4. **Supersede, don't duplicate.** If a preference changes, link to the old one.
-5. **L1 is your lifeline.** If it's not in L1 and you didn't search L2, you effectively don't remember it.
-6. **Tasks over files.** Use `task_create`/`task_update` instead of local markdown checklists. Tasks persist across sessions.
+5. **Assert relationships explicitly.** When you know two memories are related, contradictory, or one derives from another — say so with `memory_link`. The graph improves consolidation accuracy.
+6. **L1 is your lifeline.** If it's not in L1 and you didn't search L2, you effectively don't remember it.
+7. **Tasks over files.** Use `task_create`/`task_update` instead of local markdown checklists. Tasks persist across sessions.

package/dist/index.js

@@ -228,7 +228,7 @@ export const queries = {
       ORDER BY date DESC
     `),
     // -------------------------------------------------------------------
-    // Relationships with memory context
+    // Relationships
     // -------------------------------------------------------------------
     getMemoryRelationships: (db) => db.prepare(`
       SELECT
@@ -240,6 +240,15 @@ export const queries = {
       JOIN memory t ON t.id = r.to_id
       WHERE r.from_id = ? OR r.to_id = ?
     `),
+    insertRelationship: (db) => db.prepare(`
+      INSERT OR IGNORE INTO relationship (from_id, to_id, type)
+      VALUES (?, ?, ?)
+    `),
+    findRelationshipBetween: (db) => db.prepare(`
+      SELECT id FROM relationship WHERE from_id = ? AND to_id = ? AND type = ?
+    `),
+    deleteRelationship: (db) => db.prepare(`DELETE FROM relationship WHERE id = ?
+    `),
     // -------------------------------------------------------------------
     // Tasks
     // -------------------------------------------------------------------
@@ -258,6 +267,8 @@ export const queries = {
     `),
     getTaskById: (db) => db.prepare(`SELECT * FROM task WHERE id = ?`),
 };
+// Distance threshold below which two memories are considered "related"
+const AUTO_LINK_THRESHOLD = 0.4;
 // -------------------------------------------------------------------
 // Helper functions
 // -------------------------------------------------------------------
@@ -294,6 +305,26 @@ export function createMemory(db, memory) {
         }
     });
     txn();
+    // Auto-link: find semantically similar memories and create 'related' edges.
+    // Runs outside the main transaction so vec0 reflects the just-inserted embedding.
+    const similar = queries.vectorSearch(db).all(Buffer.from(memory.embedding.buffer), 6 // fetch one extra so we can skip self
+    );
+    const linkTxn = db.transaction(() => {
+        for (const s of similar) {
+            if (s.id === memoryId)
+                continue;
+            if (s.distance > AUTO_LINK_THRESHOLD)
+                break; // results are ordered by distance
+            const exists = queries.findRelationshipBetween(db).get(memoryId, s.id, 'related');
+            if (!exists) {
+                queries.insertRelationship(db).run(memoryId, s.id, 'related');
+            }
+        }
+        if (memory.supersedes_id) {
+            queries.insertRelationship(db).run(memoryId, memory.supersedes_id, 'supersedes');
+        }
+    });
+    linkTxn();
     return memoryId;
 }
 // Transaction helper

package/dist/seed.js

@@ -46,13 +46,15 @@ try {
     ], [
         'CORE: Memory system operational guide.',
         'L1=auto-loaded working memory, L2=vector search, L3=deep storage.',
-        'Tools: memory_search, memory_add, memory_update_core, memory_recent, memory_stats, memory_consolidate, journal_add, journal_recent, task_create, task_update, task_list.',
-        'NO MCP: use postnesia CLI — postnesia memory search|add|update-core|recent|stats|consolidate|relationships, postnesia journal add|recent, postnesia task create|update|list.',
+        'Tools: memory_search, memory_add, memory_update_core, memory_recent, memory_stats, memory_consolidate, memory_relationships, memory_link, memory_unlink, journal_add, journal_recent, task_create, task_update, task_list.',
+        'NO MCP: use postnesia CLI — postnesia memory search|add|update-core|recent|stats|consolidate|relationships|link|unlink, postnesia journal add|recent, postnesia task create|update|list.',
         'SESSION START: task_list(status=pending) to resume work + memory_search("lesson").',
         'TASKS: task_create(title,session_id)→in_progress→completed. Tasks persist across sessions.',
         'Core memories: update with memory_update_core, never supersede.',
         'Create memories: decisions(5), preferences(5), person(5), lessons(3-5), technical(3-4), events(1-4).',
         'Supersede regular memories via supersedes_id. Rules: search first, store decisions now, tasks over files.',
+        'Relationships: memory_add auto-links related memories (distance<0.4) and inserts supersedes edge. Manual types: supports, contradicts, derives_from. Use memory_link(fromId,toId,type) to assert explicit edges; memory_unlink(id) to remove. memory_relationships(id) to inspect graph.',
+        'Consolidation boosts well-connected memories — assert relationships explicitly to improve importance scoring.',
     ]);
     await bootstrap('WORKFLOW.md', 'workflow-principles', [
         'workflow',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postnesia/db",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "AI Agent memory context database",
   "type": "module",
   "private": false,