@trylucy/agent-memory 0.0.0-stage → 0.1.2

package/package.json

@@ -1,6 +1,86 @@
 {
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.3.1",
+    "@types/node": "26.2.0",
+    "typescript": "7.0.2"
+  },
+  "engines": {
+    "node": ">=20 <25"
+  },
   "name": "@trylucy/agent-memory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Official Lucy MCP runtime for governed agent memory. Three tools only: recall, propose, proposal status.",
+  "license": "Apache-2.0",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lucy-AI-Inc/lucy-memory-mcp.git"
+  },
+  "homepage": "https://github.com/Lucy-AI-Inc/lucy-memory-mcp",
+  "bugs": {
+    "url": "https://github.com/Lucy-AI-Inc/lucy-memory-mcp/issues"
+  },
+  "keywords": [
+    "lucy",
+    "mcp",
+    "agent-memory",
+    "governed-memory"
+  ],
+  "bin": {
+    "lucy-memory-mcp": "./src/mcp/bin.mjs"
+  },
+  "files": [
+    "src",
+    "schemas",
+    "contracts",
+    "scripts/lib/am01.mjs",
+    "README.md"
+  ],
+  "types": "./src/client/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/client/index.d.ts",
+      "import": "./src/client/index.mjs"
+    },
+    "./mcp": {
+      "types": "./src/mcp/index.d.ts",
+      "import": "./src/mcp/server.mjs"
+    },
+    "./mcp/stdio": {
+      "types": "./src/mcp/stdio.d.ts",
+      "import": "./src/mcp/stdio.mjs"
+    },
+    "./provider": {
+      "types": "./src/provider/index.d.ts",
+      "import": "./src/provider/index.mjs"
+    },
+    "./hermes": {
+      "types": "./src/integrations/hermes.d.ts",
+      "import": "./src/integrations/hermes.mjs"
+    }
+  },
+  "scripts": {
+    "check:full": "npm test && npm run test:types && npm run validate && npm run verify:hashes && npm run scan:secrets && npm audit --audit-level=moderate && npm pack --dry-run",
+    "hashes": "node scripts/generate-hashes.mjs --write",
+    "test": "node --test",
+    "test:mcp": "node --test tests/mcp/core-mcp-server.test.mjs",
+    "test:e2e": "node --test tests/e2e/wave4-isolated-e2e.test.mjs",
+    "test:package": "node --test tests/package/package-contents.test.mjs",
+    "test:types": "tsc --noEmit -p tests/types/tsconfig.json",
+    "validate": "npm run validate:contract && npm run validate:schemas",
+    "validate:contract": "node scripts/validate-contract.mjs",
+    "validate:schemas": "node scripts/validate-schemas.mjs",
+    "scan:secrets": "node scripts/scan-secrets.mjs",
+    "verify:hashes": "node scripts/generate-hashes.mjs --check"
+  },
+  "type": "module",
+  "version": "0.1.2",
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.3.1",
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "yaml": "^2.8.3"
+  },
+  "overrides": {
+    "fast-uri": "3.1.9"
+  }
+}

package/schemas/canonical-recall/response.schema.json

@@ -0,0 +1,56 @@
+{
+  "$id": "https://schemas.trylucy.ai/agent-memory/canonical-recall/response.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Canonical recall response",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "request_id", "as_of", "consistency", "scope", "results", "notices"],
+  "properties": {
+    "schema_version": { "const": "canonical-recall-1" },
+    "request_id": { "type": "string", "pattern": "^req_[A-Za-z0-9_-]+$", "maxLength": 256 },
+    "as_of": { "$ref": "#/$defs/timestamp" },
+    "consistency": { "const": "canonical_active" },
+    "scope": { "$ref": "#/$defs/scope" },
+    "results": { "type": "array", "maxItems": 5, "items": { "$ref": "#/$defs/result" } },
+    "notices": { "type": "array", "maxItems": 0 }
+  },
+  "$defs": {
+    "timestamp": { "type": "string", "format": "date-time" },
+    "scope": {
+      "oneOf": [
+        { "type": "object", "additionalProperties": false, "required": ["kind"], "properties": { "kind": { "const": "user" } } },
+        { "type": "object", "additionalProperties": false, "required": ["kind"], "properties": { "kind": { "const": "workspace" } } },
+        { "type": "object", "additionalProperties": false, "required": ["kind", "id"], "properties": { "kind": { "const": "project" }, "id": { "type": "string", "pattern": "^project_[A-Za-z0-9_-]+$", "minLength": 1, "maxLength": 128 } } }
+      ]
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "record_id", "proposal_id", "canonical_payload_hash", "written_at"],
+      "properties": {
+        "type": { "const": "lucy_canonical" },
+        "record_id": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "proposal_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 256 },
+        "canonical_payload_hash": { "type": ["string", "null"], "pattern": "^[a-fA-F0-9]{64}$" },
+        "written_at": { "$ref": "#/$defs/timestamp" }
+      }
+    },
+    "result": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["record_id", "key", "kind", "scope", "content", "status", "persisted", "approval_status", "version", "provenance"],
+      "properties": {
+        "record_id": { "type": "string", "minLength": 1, "maxLength": 256 },
+        "key": { "type": ["string", "null"], "minLength": 1, "maxLength": 128, "pattern": "^[a-z](?:[a-z0-9]|[._-](?=[a-z0-9])){0,127}$" },
+        "kind": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "scope": { "$ref": "#/$defs/scope" },
+        "content": { "type": "string", "minLength": 1, "maxLength": 8192 },
+        "status": { "const": "active" },
+        "persisted": { "const": true },
+        "approval_status": { "enum": ["user_approved", "approved", "replayed", "controller_approved"] },
+        "version": { "type": ["integer", "null"], "minimum": 1, "maximum": 9007199254740991 },
+        "provenance": { "$ref": "#/$defs/provenance" }
+      }
+    }
+  }
+}

package/schemas/v1/common.schema.json

@@ -0,0 +1,190 @@
+{
+  "$defs": {
+    "authority": {
+      "additionalProperties": false,
+      "properties": {
+        "type": {
+          "const": "human_approved"
+        }
+      },
+      "required": [
+        "type"
+      ],
+      "type": "object"
+    },
+    "content": {
+      "maxLength": 2000,
+      "minLength": 1,
+      "type": "string"
+    },
+    "contractVersion": {
+      "const": "2026-08-09"
+    },
+    "idempotencyKey": {
+      "format": "uuid",
+      "type": "string"
+    },
+    "justification": {
+      "maxLength": 500,
+      "minLength": 1,
+      "type": "string"
+    },
+    "key": {
+      "maxLength": 128,
+      "minLength": 1,
+      "pattern": "^[a-z](?:[a-z0-9]|[._-](?=[a-z0-9])){0,127}$",
+      "type": "string"
+    },
+    "memoryId": {
+      "pattern": "^mem_[A-Za-z0-9_-]+$",
+      "type": "string"
+    },
+    "memoryKind": {
+      "enum": [
+        "fact",
+        "preference",
+        "decision",
+        "rule"
+      ]
+    },
+    "memoryLifecycle": {
+      "enum": [
+        "active",
+        "superseded",
+        "revoked",
+        "forgotten"
+      ]
+    },
+    "proposalId": {
+      "pattern": "^proposal_[A-Za-z0-9_-]+$",
+      "type": "string"
+    },
+    "proposalLifecycle": {
+      "enum": [
+        "pending",
+        "approved",
+        "rejected",
+        "expired",
+        "superseded"
+      ]
+    },
+    "provenance": {
+      "additionalProperties": false,
+      "properties": {
+        "ref": {
+          "maxLength": 256,
+          "minLength": 1,
+          "type": "string"
+        },
+        "type": {
+          "const": "governed_record"
+        }
+      },
+      "required": [
+        "type",
+        "ref"
+      ],
+      "type": "object"
+    },
+    "receiptId": {
+      "pattern": "^rcpt_[A-Za-z0-9_-]+$",
+      "type": "string"
+    },
+    "relation": {
+      "additionalProperties": false,
+      "properties": {
+        "memory_id": {
+          "$ref": "#/$defs/memoryId"
+        },
+        "memory_version": {
+          "$ref": "#/$defs/version"
+        },
+        "type": {
+          "const": "supersedes"
+        }
+      },
+      "required": [
+        "type",
+        "memory_id",
+        "memory_version"
+      ],
+      "type": "object"
+    },
+    "requestId": {
+      "pattern": "^req_[A-Za-z0-9_-]+$",
+      "type": "string"
+    },
+    "schemaVersion": {
+      "const": "1"
+    },
+    "scope": {
+      "oneOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "user"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "properties": {
+            "kind": {
+              "const": "workspace"
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "properties": {
+            "id": {
+              "maxLength": 128,
+              "minLength": 1,
+              "pattern": "^project_[A-Za-z0-9_-]+$",
+              "type": "string"
+            },
+            "kind": {
+              "const": "project"
+            }
+          },
+          "required": [
+            "kind",
+            "id"
+          ],
+          "type": "object"
+        }
+      ]
+    },
+    "sourceRef": {
+      "maxLength": 256,
+      "minLength": 1,
+      "type": "string"
+    },
+    "timestamp": {
+      "format": "date-time",
+      "type": "string"
+    },
+    "expectedVersion": {
+      "maximum": 9007199254740990,
+      "minimum": 1,
+      "type": "integer"
+    },
+    "version": {
+      "maximum": 9007199254740991,
+      "minimum": 1,
+      "type": "integer"
+    }
+  },
+  "$id": "https://schemas.trylucy.ai/agent-memory/v1/common.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Lucy Agent Memory common definitions"
+}

package/schemas/v1/contract-document.schema.json

@@ -0,0 +1,277 @@
+{
+  "$id": "https://schemas.trylucy.ai/agent-memory/v1/contract-document.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "contract_name": {
+      "const": "Lucy Agent Memory API Contract"
+    },
+    "contract_version": {
+      "const": "2026-08-09"
+    },
+    "create": {
+      "const": {
+        "approved_memory_version": 1,
+        "creates_new_memory_id": true,
+        "forbidden": [
+          "memory_id",
+          "expected_version"
+        ],
+        "may_replace_active": false,
+        "required": [
+          "operation",
+          "key",
+          "kind",
+          "scope",
+          "content",
+          "justification",
+          "idempotency_key"
+        ]
+      }
+    },
+    "error_codes": {
+      "const": [
+        "unauthenticated",
+        "forbidden",
+        "not_found_or_not_visible",
+        "invalid_scope",
+        "invalid_request",
+        "unsupported_version",
+        "conflict",
+        "version_conflict",
+        "rate_limited",
+        "payload_too_large",
+        "service_unavailable",
+        "insufficient_credits",
+        "billing_unavailable"
+      ]
+    },
+    "forbidden_mcp_capabilities": {
+      "const": [
+        "memory_list",
+        "memory_resolve",
+        "memory_approve",
+        "memory_reject",
+        "memory_delete",
+        "memory_restore"
+      ]
+    },
+    "forbidden_public_permissions": {
+      "const": [
+        "memory:write",
+        "memory:approve",
+        "memory:resolve",
+        "memory:delete",
+        "memory:restore"
+      ]
+    },
+    "forgetting": {
+      "const": {
+        "physical_deletion_everywhere_promised": false,
+        "supported_path_promise": "Once Lucy confirms a memory as forgotten, it is immediately ineligible for recall through supported Lucy Agent Memory paths."
+      }
+    },
+    "identity": {
+      "const": {
+        "account_source": "server-derived",
+        "client_may_supply_account": false,
+        "client_may_supply_tenant": false,
+        "conflict_identity": [
+          "server-derived tenant",
+          "exact scope",
+          "exact key"
+        ],
+        "key_required": true,
+        "maximum_active_per_conflict_identity": 1,
+        "tenant_source": "server-derived"
+      }
+    },
+    "limits": {
+      "const": {
+        "content_max_bytes": 8192,
+        "content_max_unicode_scalars": 2000,
+        "idempotency_key_format": "uuid",
+        "justification_max_bytes": 2048,
+        "justification_max_unicode_scalars": 500,
+        "key_max_characters": 128,
+        "proposal_request_max_bytes": 12288,
+        "recall_keys_maximum": 20,
+        "recall_limit_default": 3,
+        "recall_limit_maximum": 5,
+        "recall_limit_minimum": 1,
+        "recall_query_max_unicode_scalars": 1024,
+        "recall_request_max_bytes": 8192,
+        "recall_response_max_bytes": 65536,
+        "source_ref_max_characters": 256
+      }
+    },
+    "mcp_tools": {
+      "const": [
+        "memory_recall",
+        "memory_propose",
+        "memory_proposal_status"
+      ]
+    },
+    "memory_kinds": {
+      "const": [
+        "fact",
+        "preference",
+        "decision",
+        "rule"
+      ]
+    },
+    "memory_lifecycle": {
+      "const": [
+        "active",
+        "superseded",
+        "revoked",
+        "forgotten"
+      ]
+    },
+    "proposal": {
+      "const": {
+        "authority": "server-authoritative human approval",
+        "payload_immutable_after_acceptance": true,
+        "proposal_supersession_distinct_from_memory_version_supersession": true,
+        "terminal_states_reopen": false
+      }
+    },
+    "proposal_lifecycle": {
+      "const": [
+        "pending",
+        "approved",
+        "rejected",
+        "expired",
+        "superseded"
+      ]
+    },
+    "proposal_version": {
+      "const": 1
+    },
+    "public_permissions": {
+      "const": [
+        "memory:read",
+        "memory:propose"
+      ]
+    },
+    "public_schema_version": {
+      "const": "1"
+    },
+    "recall": {
+      "const": {
+        "asynchronous_index_is_not_authority": true,
+        "canonical_active_state_rejoin_required": true,
+        "historical_receipt_requires_fresh_recall": true,
+        "normally_recallable_lifecycle": [
+          "active"
+        ]
+      }
+    },
+    "receipts": {
+      "const": {
+        "authority_types": [
+          "human_approved"
+        ],
+        "required_public_fields": [
+          "schema_version",
+          "id",
+          "memory_id",
+          "memory_version",
+          "key",
+          "kind",
+          "scope",
+          "lifecycle",
+          "authority",
+          "authoritative_at",
+          "issued_at",
+          "provenance",
+          "relations"
+        ],
+        "version_specific": true
+      }
+    },
+    "replace": {
+      "const": {
+        "expected_version_maximum": 9007199254740990,
+        "expected_version_minimum": 1,
+        "forbidden": [
+          "kind"
+        ],
+        "may_change_key": false,
+        "may_change_kind": false,
+        "may_change_scope": false,
+        "may_create_missing": false,
+        "maximum_memory_version": 9007199254740991,
+        "new_version_rule": "expected_version + 1",
+        "prior_version_transition": "superseded atomically",
+        "required": [
+          "operation",
+          "memory_id",
+          "expected_version",
+          "key",
+          "scope",
+          "content",
+          "justification",
+          "idempotency_key"
+        ],
+        "retains_memory_id": true
+      }
+    },
+    "retryable_error_codes": {
+      "const": [
+        "rate_limited",
+        "service_unavailable",
+        "billing_unavailable"
+      ]
+    },
+    "rule_non_authorities": {
+      "const": [
+        "credentials",
+        "OAuth scopes",
+        "access",
+        "approval authority",
+        "tool authority",
+        "spending authority",
+        "policy exemptions",
+        "tenant changes",
+        "project visibility",
+        "deployment authority",
+        "publication authority"
+      ]
+    },
+    "scope_kinds": {
+      "const": [
+        "user",
+        "workspace",
+        "project"
+      ]
+    }
+  },
+  "required": [
+    "contract_name",
+    "contract_version",
+    "public_schema_version",
+    "memory_kinds",
+    "scope_kinds",
+    "public_permissions",
+    "mcp_tools",
+    "proposal_lifecycle",
+    "memory_lifecycle",
+    "proposal_version",
+    "identity",
+    "create",
+    "replace",
+    "proposal",
+    "recall",
+    "receipts",
+    "rule_non_authorities",
+    "forgetting",
+    "limits",
+    "error_codes",
+    "retryable_error_codes",
+    "forbidden_public_permissions",
+    "forbidden_mcp_capabilities"
+  ],
+  "title": "Lucy Agent Memory API contract document",
+  "type": "object"
+}

package/schemas/v1/create-proposal-request.schema.json

@@ -0,0 +1,42 @@
+{
+  "$id": "https://schemas.trylucy.ai/agent-memory/v1/create-proposal-request.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "content": {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/common.schema.json#/$defs/content"
+    },
+    "idempotency_key": {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/common.schema.json#/$defs/idempotencyKey"
+    },
+    "justification": {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/common.schema.json#/$defs/justification"
+    },
+    "key": {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/common.schema.json#/$defs/key"
+    },
+    "kind": {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/common.schema.json#/$defs/memoryKind"
+    },
+    "operation": {
+      "const": "create"
+    },
+    "scope": {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/common.schema.json#/$defs/scope"
+    },
+    "source_ref": {
+      "$ref": "https://schemas.trylucy.ai/agent-memory/v1/common.schema.json#/$defs/sourceRef"
+    }
+  },
+  "required": [
+    "operation",
+    "key",
+    "kind",
+    "scope",
+    "content",
+    "justification",
+    "idempotency_key"
+  ],
+  "title": "Create memory proposal request",
+  "type": "object"
+}