@nuzo/memory-core 0.1.0

package/LICENSE

@@ -0,0 +1,176 @@
+Apache License
+Version 2.0, January 2004
+https://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the
+copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other
+entities that control, are controlled by, or are under common control with
+that entity. For the purposes of this definition, "control" means (i) the
+power, direct or indirect, to cause the direction or management of such
+entity, whether by contract or otherwise, or (ii) ownership of fifty percent
+(50%) or more of the outstanding shares, or (iii) beneficial ownership of
+such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation source,
+and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation
+or translation of a Source form, including but not limited to compiled
+object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form,
+made available under the License, as indicated by a copyright notice that is
+included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form,
+that is based on (or derived from) the Work and for which the editorial
+revisions, annotations, elaborations, or other modifications represent, as a
+whole, an original work of authorship. For the purposes of this License,
+Derivative Works shall not include works that remain separable from, or
+merely link (or bind by name) to the interfaces of, the Work and Derivative
+Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original
+version of the Work and any modifications or additions to that Work or
+Derivative Works thereof, that is intentionally submitted to Licensor for
+inclusion in the Work by the copyright owner or by an individual or Legal
+Entity authorized to submit on behalf of the copyright owner. For the
+purposes of this definition, "submitted" means any form of electronic,
+verbal, or written communication sent to the Licensor or its representatives,
+including but not limited to communication on electronic mailing lists,
+source code control systems, and issue tracking systems that are managed by,
+or on behalf of, the Licensor for the purpose of discussing and improving the
+Work, but excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on
+behalf of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+reproduce, prepare Derivative Works of, publicly display, publicly perform,
+sublicense, and distribute the Work and such Derivative Works in Source or
+Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+License, each Contributor hereby grants to You a perpetual, worldwide,
+non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
+section) patent license to make, have made, use, offer to sell, sell, import,
+and otherwise transfer the Work, where such license applies only to those
+patent claims licensable by such Contributor that are necessarily infringed
+by their Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You institute
+patent litigation against any entity (including a cross-claim or
+counterclaim in a lawsuit) alleging that the Work or a Contribution
+incorporated within the Work constitutes direct or contributory patent
+infringement, then any patent licenses granted to You under this License for
+that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+Derivative Works thereof in any medium, with or without modifications, and in
+Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy
+of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that
+You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You
+distribute, all copyright, patent, trademark, and attribution notices from
+the Source form of the Work, excluding those notices that do not pertain to
+any part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution,
+then any Derivative Works that You distribute must include a readable copy of
+the attribution notices contained within such NOTICE file, excluding those
+notices that do not pertain to any part of the Derivative Works, in at least
+one of the following places: within a NOTICE text file distributed as part of
+the Derivative Works; within the Source form or documentation, if provided
+along with the Derivative Works; or, within a display generated by the
+Derivative Works, if and wherever such third-party notices normally appear.
+The contents of the NOTICE file are for informational purposes only and do
+not modify the License. You may add Your own attribution notices within
+Derivative Works that You distribute, alongside or as an addendum to the
+NOTICE text from the Work, provided that such additional attribution notices
+cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may
+provide additional or different license terms and conditions for use,
+reproduction, or distribution of Your modifications, or for any such
+Derivative Works as a whole, provided Your use, reproduction, and
+distribution of the Work otherwise complies with the conditions stated in
+this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+Contribution intentionally submitted for inclusion in the Work by You to the
+Licensor shall be under the terms and conditions of this License, without any
+additional terms or conditions. Notwithstanding the above, nothing herein
+shall supersede or modify the terms of any separate license agreement you may
+have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+trademarks, service marks, or product names of the Licensor, except as
+required for reasonable and customary use in describing the origin of the
+Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+writing, Licensor provides the Work (and each Contributor provides its
+Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied, including, without limitation, any warranties
+or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any risks
+associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+tort (including negligence), contract, or otherwise, unless required by
+applicable law (such as deliberate and grossly negligent acts) or agreed to
+in writing, shall any Contributor be liable to You for damages, including any
+direct, indirect, special, incidental, or consequential damages of any
+character arising as a result of this License or out of the use or inability
+to use the Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all other
+commercial damages or losses), even if such Contributor has been advised of
+the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work
+or Derivative Works thereof, You may choose to offer, and charge a fee for,
+acceptance of support, warranty, indemnity, or other liability obligations
+and/or rights consistent with this License. However, in accepting such
+obligations, You may act only on Your own behalf and on Your sole
+responsibility, not on behalf of any other Contributor, and only if You agree
+to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 fabionfsc
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,12 @@
+# @nuzo/memory-core
+
+Core memory lifecycle, policy, SQLite storage, FTS recall, audit events, and
+portable import/export behavior for Nuzo.
+
+This package is the host-neutral business layer. Most users should install
+Nuzo through a supported host plugin or use the Nuzo CLI instead of consuming
+the core package directly.
+
+Documentation: https://nuzo.com.br/
+
+License: Apache-2.0

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class NuzoMemoryError extends Error {
+    readonly code: string;
+    readonly details: Record<string, unknown>;
+    constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+export declare function invariant(condition: unknown, code: string, message: string, details?: Record<string, unknown>): asserts condition;

package/dist/errors.js

@@ -0,0 +1,15 @@
+export class NuzoMemoryError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "NuzoMemoryError";
+    }
+}
+export function invariant(condition, code, message, details = {}) {
+    if (!condition) {
+        throw new NuzoMemoryError(code, message, details);
+    }
+}

package/dist/export-format.d.ts

@@ -0,0 +1,2 @@
+import type { MemoryExportDocument } from "./types.js";
+export declare function formatMemoryExportMarkdown(document: MemoryExportDocument): string;

package/dist/export-format.js

@@ -0,0 +1,58 @@
+export function formatMemoryExportMarkdown(document) {
+    const lines = [
+        "# Nuzo Memory Export",
+        "",
+        "This file is for human review. Use JSON exports for import.",
+        "",
+        "```yaml",
+        "format: nuzo-memory-export",
+        `version: ${document.version}`,
+        `exported_at: ${yamlString(document.exported_at)}`,
+        `count: ${document.memories.length}`,
+        "```",
+        "",
+        "## Memories",
+        "",
+    ];
+    if (document.memories.length === 0) {
+        lines.push("_No memories exported._", "");
+        return lines.join("\n");
+    }
+    document.memories.forEach((memory, index) => {
+        lines.push(`### Memory ${index + 1}`);
+        lines.push("");
+        lines.push(formatMemoryExportItemMetadata(memory));
+        lines.push("");
+        lines.push(memory.content);
+        lines.push("");
+    });
+    return lines.join("\n");
+}
+function formatMemoryExportItemMetadata(memory) {
+    const lines = [
+        "```yaml",
+        `scope: ${yamlString(memory.scope)}`,
+        `kind: ${yamlString(memory.kind)}`,
+        "tags:",
+        ...formatTags(memory.tags),
+        `source: ${yamlString(memory.source)}`,
+        `confidence: ${memory.confidence}`,
+        `created_at: ${yamlString(memory.created_at)}`,
+        `updated_at: ${yamlString(memory.updated_at)}`,
+        `last_used_at: ${yamlNullableString(memory.last_used_at)}`,
+        `archived_at: ${yamlNullableString(memory.archived_at)}`,
+        "```",
+    ];
+    return lines.join("\n");
+}
+function formatTags(tags) {
+    return tags.length === 0
+        ? ["  []"]
+        : tags.map((tag) => `  - ${yamlString(tag)}`);
+}
+function yamlNullableString(value) {
+    return value === null ? "null" : yamlString(value);
+}
+function yamlString(value) {
+    return JSON.stringify(value);
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./errors.js";
+export * from "./export-format.js";
+export * from "./policy.js";
+export * from "./ports.js";
+export * from "./runtime.js";
+export * from "./secrets.js";
+export * from "./service.js";
+export * from "./sqlite/adapter.js";
+export * from "./sqlite/schema.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from "./errors.js";
+export * from "./export-format.js";
+export * from "./policy.js";
+export * from "./ports.js";
+export * from "./runtime.js";
+export * from "./secrets.js";
+export * from "./service.js";
+export * from "./sqlite/adapter.js";
+export * from "./sqlite/schema.js";
+export * from "./types.js";

package/dist/policy.d.ts

@@ -0,0 +1,12 @@
+import type { PolicyEngine, SecretScanner } from "./ports.js";
+import type { ListMemoriesInput, MemoryRecord, RecallMemoriesInput, RememberMemoryInput, UpdateMemoryInput } from "./types.js";
+export declare const memoryScopePattern: RegExp;
+export declare const memoryTagPattern: RegExp;
+export declare class DefaultPolicyEngine implements PolicyEngine {
+    private readonly secretScanner;
+    constructor(secretScanner: SecretScanner);
+    assertCanRemember(input: RememberMemoryInput): Promise<void>;
+    assertCanUpdate(input: UpdateMemoryInput, current: MemoryRecord): Promise<void>;
+    assertCanRecall(input: RecallMemoriesInput): Promise<void>;
+    assertCanList(input: ListMemoriesInput): Promise<void>;
+}

package/dist/policy.js

@@ -0,0 +1,63 @@
+import { invariant } from "./errors.js";
+import { memoryKinds } from "./types.js";
+export const memoryScopePattern = /^(user|project|agent|team):[A-Za-z0-9._~:/-]+$/;
+export const memoryTagPattern = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+export class DefaultPolicyEngine {
+    secretScanner;
+    constructor(secretScanner) {
+        this.secretScanner = secretScanner;
+    }
+    async assertCanRemember(input) {
+        invariant(input.content.trim().length > 0, "MEMORY_CONTENT_EMPTY", "Memory content cannot be empty.");
+        invariant(input.content.length <= 8000, "MEMORY_CONTENT_TOO_LONG", "Memory content is too long.", { maxLength: 8000 });
+        invariant(memoryKinds.includes(input.kind), "MEMORY_KIND_UNSUPPORTED", "Memory kind is not supported.", { kind: input.kind });
+        assertScope(input.scope);
+        invariant(input.source.trim().length > 0, "MEMORY_SOURCE_EMPTY", "Memory source cannot be empty.");
+        const confidence = input.confidence ?? 1;
+        invariant(confidence >= 0 && confidence <= 1, "MEMORY_CONFIDENCE_INVALID", "Memory confidence must be between 0 and 1.", { confidence });
+        for (const tag of input.tags ?? []) {
+            assertTag(tag);
+        }
+        const secretScan = await this.secretScanner.scan(input.content);
+        invariant(secretScan.ok, "MEMORY_SECRET_DETECTED", "Memory content looks sensitive.", {
+            findings: secretScan.findings,
+        });
+    }
+    async assertCanUpdate(input, current) {
+        await this.assertCanRemember({
+            content: input.content ?? current.content,
+            kind: input.kind ?? current.kind,
+            scope: input.scope ?? current.scope,
+            tags: input.tags ?? current.tags,
+            source: current.source,
+            confidence: input.confidence ?? current.confidence,
+        });
+        invariant(input.actor.trim().length > 0, "MEMORY_ACTOR_EMPTY", "Memory actor cannot be empty.");
+    }
+    async assertCanRecall(input) {
+        invariant(input.query.trim().length > 0, "RECALL_QUERY_EMPTY", "Recall query cannot be empty.");
+        assertScope(input.scope);
+        const limit = input.limit ?? 8;
+        invariant(limit > 0 && limit <= 50, "RECALL_LIMIT_INVALID", "Recall limit must be 1-50.", {
+            limit,
+        });
+    }
+    async assertCanList(input) {
+        if (input.scope !== undefined) {
+            assertScope(input.scope);
+        }
+        for (const tag of input.tags ?? []) {
+            assertTag(tag);
+        }
+    }
+}
+function assertScope(scope) {
+    invariant(memoryScopePattern.test(scope), "MEMORY_SCOPE_INVALID", "Memory scope is invalid.", {
+        scope,
+    });
+}
+function assertTag(tag) {
+    invariant(memoryTagPattern.test(tag), "MEMORY_TAG_INVALID", "Memory tag is invalid.", {
+        tag,
+    });
+}

package/dist/ports.d.ts

@@ -0,0 +1,45 @@
+import type { ListMemoriesInput, MemoryEvent, MemoryRecord, RecallMemoriesInput, RecallMemoryResult, RememberMemoryInput, UpdateMemoryInput } from "./types.js";
+export interface MemoryStore {
+    create(memory: MemoryRecord): Promise<void>;
+    update(memory: MemoryRecord): Promise<void>;
+    findById(id: string): Promise<MemoryRecord | null>;
+    list(filter: ListMemoriesInput): Promise<MemoryRecord[]>;
+    archive(id: string, archivedAt: Date): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+export interface SearchIndex {
+    index(memory: MemoryRecord): Promise<void>;
+    remove(memoryId: string): Promise<void>;
+    search(input: RecallMemoriesInput): Promise<RecallMemoryResult[]>;
+}
+export interface AuditLog {
+    append(event: MemoryEvent): Promise<void>;
+    list(memoryId: string): Promise<MemoryEvent[]>;
+}
+export interface TransactionManager {
+    run<T>(operation: () => Promise<T>): Promise<T>;
+}
+export interface Clock {
+    now(): Date;
+}
+export interface IdGenerator {
+    memoryId(): string;
+    eventId(): string;
+}
+export interface SecretScanner {
+    scan(content: string): Promise<SecretScanResult>;
+}
+export interface SecretScanResult {
+    ok: boolean;
+    findings: SecretFinding[];
+}
+export interface SecretFinding {
+    kind: string;
+    message: string;
+}
+export interface PolicyEngine {
+    assertCanRemember(input: RememberMemoryInput): Promise<void>;
+    assertCanUpdate(input: UpdateMemoryInput, current: MemoryRecord): Promise<void>;
+    assertCanRecall(input: RecallMemoriesInput): Promise<void>;
+    assertCanList(input: ListMemoriesInput): Promise<void>;
+}

package/dist/ports.js

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

package/dist/runtime.d.ts

@@ -0,0 +1,8 @@
+import type { Clock, IdGenerator } from "./ports.js";
+export declare class SystemClock implements Clock {
+    now(): Date;
+}
+export declare class RandomIdGenerator implements IdGenerator {
+    memoryId(): string;
+    eventId(): string;
+}

package/dist/runtime.js

@@ -0,0 +1,14 @@
+import { randomUUID } from "node:crypto";
+export class SystemClock {
+    now() {
+        return new Date();
+    }
+}
+export class RandomIdGenerator {
+    memoryId() {
+        return `mem_${randomUUID()}`;
+    }
+    eventId() {
+        return `evt_${randomUUID()}`;
+    }
+}

package/dist/secrets.d.ts

@@ -0,0 +1,4 @@
+import type { SecretScanner, SecretScanResult } from "./ports.js";
+export declare class RegexSecretScanner implements SecretScanner {
+    scan(content: string): Promise<SecretScanResult>;
+}

package/dist/secrets.js

@@ -0,0 +1,64 @@
+const patterns = [
+    {
+        kind: "private_key",
+        regex: /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/,
+        message: "Private key material should not be stored as memory.",
+    },
+    {
+        kind: "github_token",
+        regex: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{20,}\b/,
+        message: "GitHub tokens should not be stored as memory.",
+    },
+    {
+        kind: "provider_api_key",
+        regex: /\b(?:sk-(?:proj-|ant-[A-Za-z0-9-]+-)?[A-Za-z0-9_-]{20,}|sk_live_[A-Za-z0-9]{20,}|AIza[A-Za-z0-9_-]{30,})\b/,
+        message: "Provider API keys should not be stored as memory.",
+    },
+    {
+        kind: "aws_access_key",
+        regex: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/,
+        message: "AWS access keys should not be stored as memory.",
+    },
+    {
+        kind: "jwt",
+        regex: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/,
+        message: "JSON Web Tokens should not be stored as memory.",
+    },
+    {
+        kind: "bearer_token",
+        regex: /\bBearer\s+(?!(?:redacted|placeholder|example)\b)[A-Za-z0-9._~+/-]{20,}=*\b/i,
+        message: "Bearer tokens should not be stored as memory.",
+    },
+    {
+        kind: "credential_url",
+        regex: /\b(?:postgres(?:ql)?|mysql|mariadb|mongodb(?:\+srv)?|redis|rediss):\/\/[^:\s/@]+:(?!(?:redacted|password|placeholder|changeme|\*+)@)[^@\s/]{4,}@/i,
+        message: "Database URLs containing credentials should not be stored as memory.",
+    },
+    {
+        kind: "session_cookie",
+        regex: /\b(?:cookie|set-cookie|session(?:_?id)?)\s*[:=]\s*['"]?(?!(?:redacted|placeholder|example|\*+)\b)[A-Za-z0-9%._~+/=-]{16,}/i,
+        message: "Cookie and session values should not be stored as memory.",
+    },
+    {
+        kind: "generic_api_key",
+        regex: /\b(?:api[_-]?key|token|secret|password)\s*[:=]\s*['"]?(?!(?:redacted|placeholder|example|changeme|\*+)\b)[A-Za-z0-9._~/-]{16,}/i,
+        message: "Credentials should not be stored as memory.",
+    },
+];
+export class RegexSecretScanner {
+    async scan(content) {
+        const findings = [];
+        for (const pattern of patterns) {
+            if (pattern.regex.test(content)) {
+                findings.push({
+                    kind: pattern.kind,
+                    message: pattern.message,
+                });
+            }
+        }
+        return {
+            ok: findings.length === 0,
+            findings,
+        };
+    }
+}

package/dist/service.d.ts

@@ -0,0 +1,23 @@
+import type { AuditLog, Clock, IdGenerator, MemoryStore, PolicyEngine, SearchIndex, TransactionManager } from "./ports.js";
+import type { ExportMemoriesInput, ForgetMemoryInput, ForgetMemoriesInput, ForgetMemoriesResult, ImportMemoriesInput, ImportMemoriesResult, ListMemoriesInput, MemoryExportDocument, MemoryEvent, MemoryRecord, RecallMemoriesInput, RecallMemoryResult, RememberMemoryInput, UpdateMemoryInput } from "./types.js";
+export interface MemoryServiceDependencies {
+    store: MemoryStore;
+    searchIndex: SearchIndex;
+    auditLog: AuditLog;
+    clock: Clock;
+    ids: IdGenerator;
+    policy: PolicyEngine;
+    transactions?: TransactionManager;
+}
+export interface MemoryService {
+    remember(input: RememberMemoryInput): Promise<MemoryRecord>;
+    recall(input: RecallMemoriesInput): Promise<RecallMemoryResult[]>;
+    list(input?: ListMemoriesInput): Promise<MemoryRecord[]>;
+    update(input: UpdateMemoryInput): Promise<MemoryRecord>;
+    history(memoryId: string): Promise<MemoryEvent[]>;
+    exportMemories(input: ExportMemoriesInput): Promise<MemoryExportDocument>;
+    importMemories(input: ImportMemoriesInput): Promise<ImportMemoriesResult>;
+    forget(input: ForgetMemoryInput): Promise<void>;
+    forgetMany(input: ForgetMemoriesInput): Promise<ForgetMemoriesResult>;
+}
+export declare function createMemoryService(dependencies: MemoryServiceDependencies): MemoryService;