@levalicious/server-memory 0.0.11 → 0.0.13

package/dist/tests/memory-server.test.js

@@ -44,9 +44,10 @@ describe('MCP Memory Server E2E Tests', () => {
             await callTool(client, 'create_entities', {
                 entities: [{ name: 'Alice', entityType: 'Person', observations: ['First'] }]
             });
+            // Exact same entity should be silently skipped
             const result = await callTool(client, 'create_entities', {
                 entities: [
-                    { name: 'Alice', entityType: 'Person', observations: ['Second'] },
+                    { name: 'Alice', entityType: 'Person', observations: ['First'] },
                     { name: 'Bob', entityType: 'Person', observations: ['New'] }
                 ]
             });
@@ -54,6 +55,19 @@ describe('MCP Memory Server E2E Tests', () => {
             expect(result).toHaveLength(1);
             expect(result[0].name).toBe('Bob');
         });
+        it('should error on duplicate name with different data', async () => {
+            await callTool(client, 'create_entities', {
+                entities: [{ name: 'Alice', entityType: 'Person', observations: ['First'] }]
+            });
+            // Same name, different type — should error
+            await expect(callTool(client, 'create_entities', {
+                entities: [{ name: 'Alice', entityType: 'Organization', observations: ['First'] }]
+            })).rejects.toThrow(/already exists/);
+            // Same name, different observations — should error
+            await expect(callTool(client, 'create_entities', {
+                entities: [{ name: 'Alice', entityType: 'Person', observations: ['Different'] }]
+            })).rejects.toThrow(/already exists/);
+        });
         it('should reject entities with more than 2 observations', async () => {
             await expect(callTool(client, 'create_entities', {
                 entities: [{
@@ -257,13 +271,6 @@ describe('MCP Memory Server E2E Tests', () => {
             // A->B and A->C both have from='A' which is in the set
             expect(result.relations.items).toHaveLength(2);
         });
-        it('should open nodes filtered (only internal relations)', async () => {
-            const result = await callTool(client, 'open_nodes_filtered', {
-                names: ['B', 'C']
-            });
-            expect(result.entities.items).toHaveLength(2);
-            expect(result.relations.items).toHaveLength(0); // No relations between B and C
-        });
     });
     describe('Graph Traversal', () => {
         beforeEach(async () => {
@@ -446,15 +453,21 @@ describe('MCP Memory Server E2E Tests', () => {
             const names = strict.items.map(e => e.name).sort();
             expect(names).toEqual(['Island1', 'Island2']);
         });
-        it('should validate graph and report violations', async () => {
-            // Directly write invalid data to test validation
-            const invalidData = [
-                JSON.stringify({ type: 'entity', name: 'Valid', entityType: 'Test', observations: [] }),
-                JSON.stringify({ type: 'relation', from: 'Valid', to: 'Missing', relationType: 'refs' })
-            ].join('\n');
-            await fs.writeFile(memoryFile, invalidData);
+        it('should validate graph and report no violations on clean graph', async () => {
+            // Create a valid graph through the API
+            await callTool(client, 'create_entities', {
+                entities: [
+                    { name: 'Valid', entityType: 'Test', observations: [] },
+                    { name: 'Also_Valid', entityType: 'Test', observations: ['Short obs'] }
+                ]
+            });
+            await callTool(client, 'create_relations', {
+                relations: [{ from: 'Valid', to: 'Also_Valid', relationType: 'refs' }]
+            });
             const result = await callTool(client, 'validate_graph', {});
-            expect(result.missingEntities).toContain('Missing');
+            // Binary store enforces referential integrity — no missing entities possible
+            expect(result.missingEntities).toHaveLength(0);
+            expect(result.observationViolations).toHaveLength(0);
         });
     });
     describe('Sequential Thinking', () => {
@@ -620,12 +633,16 @@ describe('MCP Memory Server E2E Tests', () => {
                     { name: 'Gamma', entityType: 'Letter', observations: ['Third letter'] }
                 ]);
             });
-            it('should preserve insertion order when sortBy is omitted', async () => {
+            it('should use llmrank as default sort when sortBy is omitted', async () => {
                 const result = await callTool(client, 'search_nodes', {
                     query: 'Letter'
                 });
+                // With llmrank default, all entities returned (order varies due to random tiebreak)
                 const names = result.entities.items.map(e => e.name);
-                expect(names).toEqual(['Alpha', 'Beta', 'Gamma']);
+                expect(names).toHaveLength(3);
+                expect(names).toContain('Alpha');
+                expect(names).toContain('Beta');
+                expect(names).toContain('Gamma');
             });
             it('should sort by name ascending', async () => {
                 const result = await callTool(client, 'search_nodes', {
@@ -689,12 +706,16 @@ describe('MCP Memory Server E2E Tests', () => {
                     { name: 'Monkey', entityType: 'Animal', observations: ['Clever'] }
                 ]);
             });
-            it('should preserve insertion order when sortBy is omitted', async () => {
+            it('should use llmrank as default sort when sortBy is omitted', async () => {
                 const result = await callTool(client, 'get_entities_by_type', {
                     entityType: 'Animal'
                 });
+                // With llmrank default, all entities returned (order varies due to random tiebreak)
                 const names = result.items.map(e => e.name);
-                expect(names).toEqual(['Zebra', 'Aardvark', 'Monkey']);
+                expect(names).toHaveLength(3);
+                expect(names).toContain('Zebra');
+                expect(names).toContain('Aardvark');
+                expect(names).toContain('Monkey');
             });
             it('should sort by name ascending (default for name)', async () => {
                 const result = await callTool(client, 'get_entities_by_type', {
@@ -742,10 +763,14 @@ describe('MCP Memory Server E2E Tests', () => {
                     { name: 'Orphan_M', entityType: 'Orphan', observations: ['Isolated'] }
                 ]);
             });
-            it('should preserve insertion order when sortBy is omitted', async () => {
+            it('should use llmrank as default sort when sortBy is omitted', async () => {
                 const result = await callTool(client, 'get_orphaned_entities', {});
+                // With llmrank default, all entities returned (order varies due to random tiebreak)
                 const names = result.items.map(e => e.name);
-                expect(names).toEqual(['Orphan_Z', 'Orphan_A', 'Orphan_M']);
+                expect(names).toHaveLength(3);
+                expect(names).toContain('Orphan_Z');
+                expect(names).toContain('Orphan_A');
+                expect(names).toContain('Orphan_M');
             });
             it('should sort by name ascending', async () => {
                 const result = await callTool(client, 'get_orphaned_entities', {
@@ -807,12 +832,12 @@ describe('MCP Memory Server E2E Tests', () => {
                     ]
                 });
             });
-            it('should return unsorted neighbors when sortBy is omitted', async () => {
+            it('should use llmrank as default sort when sortBy is omitted', async () => {
                 const result = await callTool(client, 'get_neighbors', {
                     entityName: 'Hub'
                 });
+                // With llmrank default, all neighbors returned (order varies due to random tiebreak)
                 expect(result.items).toHaveLength(3);
-                // Just verify all neighbors are present
                 const names = result.items.map(n => n.name);
                 expect(names).toContain('Neighbor_Z');
                 expect(names).toContain('Neighbor_A');
@@ -915,5 +940,91 @@ describe('MCP Memory Server E2E Tests', () => {
                 expect(names).toEqual(sortedNames);
             });
         });
+        describe('pagerank sorting', () => {
+            it('should sort by pagerank (structural rank)', async () => {
+                // Build a star graph: Hub -> A, Hub -> B, Hub -> C
+                // A, B, C are dangling nodes
+                await callTool(client, 'create_entities', {
+                    entities: [
+                        { name: 'Hub', entityType: 'Node', observations: ['Central node'] },
+                        { name: 'LeafA', entityType: 'Node', observations: ['Leaf A'] },
+                        { name: 'LeafB', entityType: 'Node', observations: ['Leaf B'] },
+                        { name: 'LeafC', entityType: 'Node', observations: ['Leaf C'] },
+                    ]
+                });
+                await callTool(client, 'create_relations', {
+                    relations: [
+                        { from: 'Hub', to: 'LeafA', relationType: 'LINKS' },
+                        { from: 'Hub', to: 'LeafB', relationType: 'LINKS' },
+                        { from: 'Hub', to: 'LeafC', relationType: 'LINKS' },
+                    ]
+                });
+                // Sort by pagerank descending (default for ranks)
+                const result = await callTool(client, 'search_nodes', {
+                    query: 'Node',
+                    sortBy: 'pagerank'
+                });
+                // All entities should be returned
+                expect(result.entities.items).toHaveLength(4);
+                // With structural rank, the leaves should rank higher than the hub
+                // because they receive visits from Hub's walks.
+                // We just verify the sort works and returns all entities.
+                const names = result.entities.items.map(e => e.name);
+                expect(names).toContain('Hub');
+                expect(names).toContain('LeafA');
+                expect(names).toContain('LeafB');
+                expect(names).toContain('LeafC');
+            });
+        });
+        describe('llmrank sorting', () => {
+            it('should sort by llmrank (walker visits)', async () => {
+                await callTool(client, 'create_entities', {
+                    entities: [
+                        { name: 'Hot', entityType: 'Test', observations: ['Frequently accessed'] },
+                        { name: 'Cold', entityType: 'Test', observations: ['Rarely accessed'] },
+                    ]
+                });
+                // Access 'Hot' multiple times via open_nodes (which increments walker visits)
+                await callTool(client, 'open_nodes', { names: ['Hot'] });
+                await callTool(client, 'open_nodes', { names: ['Hot'] });
+                await callTool(client, 'open_nodes', { names: ['Hot'] });
+                await callTool(client, 'open_nodes', { names: ['Hot'] });
+                await callTool(client, 'open_nodes', { names: ['Hot'] });
+                // Access 'Cold' just once
+                await callTool(client, 'open_nodes', { names: ['Cold'] });
+                // Sort by llmrank descending
+                const result = await callTool(client, 'search_nodes', {
+                    query: 'Test',
+                    sortBy: 'llmrank'
+                });
+                // 'Hot' should rank higher than 'Cold' due to more walker visits
+                expect(result.entities.items).toHaveLength(2);
+                expect(result.entities.items[0].name).toBe('Hot');
+                expect(result.entities.items[1].name).toBe('Cold');
+            });
+            it('should fall back to pagerank on llmrank tie', async () => {
+                // Create entities with no prior walker visits
+                await callTool(client, 'create_entities', {
+                    entities: [
+                        { name: 'Center', entityType: 'Fallback', observations: ['Hub'] },
+                        { name: 'Spoke', entityType: 'Fallback', observations: ['Leaf'] },
+                    ]
+                });
+                // Create a relation so structural rank differs
+                await callTool(client, 'create_relations', {
+                    relations: [{ from: 'Center', to: 'Spoke', relationType: 'POINTS_TO' }]
+                });
+                // Both have 0 walker visits (tie), so llmrank should fall back to pagerank
+                const result = await callTool(client, 'search_nodes', {
+                    query: 'Fallback',
+                    sortBy: 'llmrank'
+                });
+                // Just verify we get both entities (ordering depends on structural rank + random tiebreak)
+                expect(result.entities.items).toHaveLength(2);
+                const names = result.entities.items.map(e => e.name);
+                expect(names).toContain('Center');
+                expect(names).toContain('Spoke');
+            });
+        });
     });
 });

package/native/binding.c

@@ -0,0 +1,340 @@
+/*
+ * N-API binding for memoryfile
+ *
+ * Exposes the C memoryfile allocator to Node.js.
+ * Each MemoryFile handle is wrapped in a pointerless external.
+ */
+
+#define NAPI_VERSION 8
+#include <node_api.h>
+#include <stdlib.h>
+#include <string.h>
+#include "memoryfile.h"
+
+/* =========================================================================
+ * Helpers
+ * ========================================================================= */
+
+#define NAPI_CALL(call)                                                    \
+    do {                                                                   \
+        napi_status status = (call);                                       \
+        if (status != napi_ok) {                                           \
+            napi_throw_error(env, NULL, "N-API call failed: " #call);      \
+            return NULL;                                                   \
+        }                                                                  \
+    } while (0)
+
+static napi_value make_u64(napi_env env, u64 val) {
+    /* Use BigInt for u64 to avoid precision loss */
+    napi_value result;
+    NAPI_CALL(napi_create_bigint_uint64(env, val, &result));
+    return result;
+}
+
+static u64 get_u64(napi_env env, napi_value val) {
+    bool lossless;
+    uint64_t result;
+    napi_get_value_bigint_uint64(env, val, &result, &lossless);
+    return result;
+}
+
+static void mf_release(napi_env env, void *data, void *hint) {
+    (void)env; (void)hint;
+    memfile_t *mf = (memfile_t*)data;
+    if (mf) {
+        memfile_close(mf);  /* no-op if already closed */
+        mf->mmap_base = NULL;
+        mf->header = NULL;
+        free(mf);
+    }
+}
+
+static memfile_t *unwrap_mf(napi_env env, napi_value val) {
+    memfile_t *mf;
+    napi_get_value_external(env, val, (void**)&mf);
+    return mf;
+}
+
+/* =========================================================================
+ * memfile_open(path: string, initialSize: number) => external
+ * ========================================================================= */
+
+static napi_value n_memfile_open(napi_env env, napi_callback_info info) {
+    size_t argc = 2;
+    napi_value argv[2];
+    NAPI_CALL(napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
+
+    /* Get path string */
+    char path[4096];
+    size_t path_len;
+    NAPI_CALL(napi_get_value_string_utf8(env, argv[0], path, sizeof(path), &path_len));
+
+    /* Get initial size */
+    uint32_t initial_size;
+    NAPI_CALL(napi_get_value_uint32(env, argv[1], &initial_size));
+
+    memfile_t *mf = memfile_open(path, (size_t)initial_size);
+    if (!mf) {
+        napi_throw_error(env, NULL, "memfile_open failed");
+        return NULL;
+    }
+
+    napi_value result;
+    NAPI_CALL(napi_create_external(env, mf, mf_release, NULL, &result));
+    return result;
+}
+
+/* =========================================================================
+ * memfile_close(handle: external) => void
+ * ========================================================================= */
+
+static napi_value n_memfile_close(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value argv[1];
+    NAPI_CALL(napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
+
+    memfile_t *mf = unwrap_mf(env, argv[0]);
+    memfile_close(mf);
+
+    return NULL;
+}
+
+/* =========================================================================
+ * memfile_sync(handle: external) => void
+ * ========================================================================= */
+
+static napi_value n_memfile_sync(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value argv[1];
+    NAPI_CALL(napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
+
+    memfile_t *mf = unwrap_mf(env, argv[0]);
+    memfile_sync(mf);
+
+    return NULL;
+}
+
+/* =========================================================================
+ * memfile_alloc(handle: external, size: bigint) => bigint (offset)
+ * ========================================================================= */
+
+static napi_value n_memfile_alloc(napi_env env, napi_callback_info info) {
+    size_t argc = 2;
+    napi_value argv[2];
+    NAPI_CALL(napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
+
+    memfile_t *mf = unwrap_mf(env, argv[0]);
+    u64 size = get_u64(env, argv[1]);
+
+    u64 offset = memfile_alloc(mf, size);
+    return make_u64(env, offset);
+}
+
+/* =========================================================================
+ * memfile_free(handle: external, offset: bigint) => void
+ * ========================================================================= */
+
+static napi_value n_memfile_free(napi_env env, napi_callback_info info) {
+    size_t argc = 2;
+    napi_value argv[2];
+    NAPI_CALL(napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
+
+    memfile_t *mf = unwrap_mf(env, argv[0]);
+    u64 offset = get_u64(env, argv[1]);
+
+    memfile_free(mf, offset);
+
+    return NULL;
+}
+
+/* =========================================================================
+ * memfile_coalesce(handle: external) => void
+ * ========================================================================= */
+
+static napi_value n_memfile_coalesce(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value argv[1];
+    NAPI_CALL(napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
+
+    memfile_t *mf = unwrap_mf(env, argv[0]);
+    memfile_coalesce(mf);
+
+    return NULL;
+}
+
+/* =========================================================================
+ * memfile_read(handle: external, offset: bigint, length: bigint) => Buffer
+ * ========================================================================= */
+
+static napi_value n_memfile_read(napi_env env, napi_callback_info info) {
+    size_t argc = 3;
+    napi_value argv[3];
+    NAPI_CALL(napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
+
+    memfile_t *mf = unwrap_mf(env, argv[0]);
+    u64 offset = get_u64(env, argv[1]);
+    u64 len = get_u64(env, argv[2]);
+
+    /* Create a Node Buffer and copy data into it */
+    void *buf_data;
+    napi_value result;
+    NAPI_CALL(napi_create_buffer(env, (size_t)len, &buf_data, &result));
+
+    if (memfile_read(mf, offset, buf_data, len) < 0) {
+        napi_throw_error(env, NULL, "memfile_read: offset/length out of bounds");
+        return NULL;
+    }
+
+    return result;
+}
+
+/* =========================================================================
+ * memfile_write(handle: external, offset: bigint, data: Buffer) => void
+ * ========================================================================= */
+
+static napi_value n_memfile_write(napi_env env, napi_callback_info info) {
+    size_t argc = 3;
+    napi_value argv[3];
+    NAPI_CALL(napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
+
+    memfile_t *mf = unwrap_mf(env, argv[0]);
+    u64 offset = get_u64(env, argv[1]);
+
+    /* Get Buffer data */
+    void *buf_data;
+    size_t buf_len;
+    NAPI_CALL(napi_get_buffer_info(env, argv[2], &buf_data, &buf_len));
+
+    if (memfile_write(mf, offset, buf_data, buf_len) < 0) {
+        napi_throw_error(env, NULL, "memfile_write: offset/length out of bounds");
+        return NULL;
+    }
+
+    return NULL;
+}
+
+/* =========================================================================
+ * memfile_lock_shared(handle: external) => void
+ * ========================================================================= */
+
+static napi_value n_memfile_lock_shared(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value argv[1];
+    NAPI_CALL(napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
+
+    memfile_t *mf = unwrap_mf(env, argv[0]);
+    if (memfile_lock_shared(mf) < 0) {
+        napi_throw_error(env, NULL, "memfile_lock_shared failed");
+        return NULL;
+    }
+
+    return NULL;
+}
+
+/* =========================================================================
+ * memfile_lock_exclusive(handle: external) => void
+ * ========================================================================= */
+
+static napi_value n_memfile_lock_exclusive(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value argv[1];
+    NAPI_CALL(napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
+
+    memfile_t *mf = unwrap_mf(env, argv[0]);
+    if (memfile_lock_exclusive(mf) < 0) {
+        napi_throw_error(env, NULL, "memfile_lock_exclusive failed");
+        return NULL;
+    }
+
+    return NULL;
+}
+
+/* =========================================================================
+ * memfile_unlock(handle: external) => void
+ * ========================================================================= */
+
+static napi_value n_memfile_unlock(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value argv[1];
+    NAPI_CALL(napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
+
+    memfile_t *mf = unwrap_mf(env, argv[0]);
+    if (memfile_unlock(mf) < 0) {
+        napi_throw_error(env, NULL, "memfile_unlock failed");
+        return NULL;
+    }
+
+    return NULL;
+}
+
+/* =========================================================================
+ * memfile_stats(handle: external) => { fileSize, allocated, freeListHead }
+ * ========================================================================= */
+
+static napi_value n_memfile_stats(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value argv[1];
+    NAPI_CALL(napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
+
+    memfile_t *mf = unwrap_mf(env, argv[0]);
+
+    napi_value result;
+    NAPI_CALL(napi_create_object(env, &result));
+
+    napi_value v;
+    NAPI_CALL(napi_create_bigint_uint64(env, mf->header->file_size, &v));
+    NAPI_CALL(napi_set_named_property(env, result, "fileSize", v));
+
+    NAPI_CALL(napi_create_bigint_uint64(env, mf->header->allocated, &v));
+    NAPI_CALL(napi_set_named_property(env, result, "allocated", v));
+
+    NAPI_CALL(napi_create_bigint_uint64(env, mf->header->free_list_head, &v));
+    NAPI_CALL(napi_set_named_property(env, result, "freeListHead", v));
+
+    return result;
+}
+
+/* =========================================================================
+ * memfile_refresh(handle: external) => void
+ * ========================================================================= */
+
+static napi_value n_memfile_refresh(napi_env env, napi_callback_info info) {
+    size_t argc = 1;
+    napi_value argv[1];
+    NAPI_CALL(napi_get_cb_info(env, info, &argc, argv, NULL, NULL));
+
+    memfile_t *mf = unwrap_mf(env, argv[0]);
+    if (memfile_refresh(mf) < 0) {
+        napi_throw_error(env, NULL, "memfile_refresh failed");
+        return NULL;
+    }
+
+    return NULL;
+}
+
+/* =========================================================================
+ * Module init
+ * ========================================================================= */
+
+#define EXPORT_FN(name, fn) do {                                               \
+    napi_value _fn;                                                            \
+    napi_create_function(env, name, NAPI_AUTO_LENGTH, fn, NULL, &_fn);         \
+    napi_set_named_property(env, exports, name, _fn);                          \
+} while(0)
+
+NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
+    EXPORT_FN("open",          n_memfile_open);
+    EXPORT_FN("close",         n_memfile_close);
+    EXPORT_FN("sync",          n_memfile_sync);
+    EXPORT_FN("alloc",         n_memfile_alloc);
+    EXPORT_FN("free",          n_memfile_free);
+    EXPORT_FN("coalesce",      n_memfile_coalesce);
+    EXPORT_FN("read",          n_memfile_read);
+    EXPORT_FN("write",         n_memfile_write);
+    EXPORT_FN("lockShared",    n_memfile_lock_shared);
+    EXPORT_FN("lockExclusive", n_memfile_lock_exclusive);
+    EXPORT_FN("unlock",        n_memfile_unlock);
+    EXPORT_FN("stats",         n_memfile_stats);
+    EXPORT_FN("refresh",       n_memfile_refresh);
+    return exports;
+}