Use DATABASE_URL and rename Postgres schema knowledge → memory

Hosts pass memory.databaseUrl or DATABASE_URL (same Postgres as the hub is
fine); tables live under the memory schema. KNOWLEDGE_DATABASE_URL remains a
deprecated alias. Fresh installs only for the schema rename.

Author: TheGreatAxios

AGENTS.md

@@ -11,7 +11,7 @@ port, or process entrypoint here, and there never should be.
 bun install              # Bun 1.2+ required
 bun run typecheck        # tsc --noEmit
 bun run test             # bun test ./src (no network, no Postgres)
-bun run db:setup         # apply migrations (needs KNOWLEDGE_DATABASE_URL)
+bun run db:setup         # apply migrations (needs DATABASE_URL)
 docker compose up -d     # local pgvector + model endpoints for manual runs
 ```
 
@@ -28,7 +28,7 @@ CI runs `typecheck` + `test` — both must pass before any push.
 - `src/services/` — capture / search / transform internals (not public verbs)
 - `src/ports/` — `DocumentStore` / `SourceProvider` + fakes
 - `src/core/` — embed/rerank clients, merge, arktype schemas
-- `src/db/` + `migrations/` — Drizzle schema + SQL migrations (pgvector, `knowledge.*`)
+- `src/db/` + `migrations/` — Drizzle schema + SQL migrations (pgvector, `memory.*`)
 - `packages/` — removed; DocumentStore adapters and Linear tools are sibling packages
   (`@corbits/mem0-memory-adapter`, `@corbits/supermemory-memory-adapter`,
   `@corbits/linear-tools`).
@@ -38,10 +38,11 @@ CI runs `typecheck` + `test` — both must pass before any push.
 1. **Authenticate nothing.** Identity is `c.get("principal")` from the
    Interchange context; authorization goes through the host's grant store
    (`@intx/authz`). Never add API keys, sessions, or OAuth here.
-2. **One Postgres**: `KNOWLEDGE_DATABASE_URL`, the engine's own vector plane.
-   There is deliberately no `DATABASE_URL` fallback — the host's control-plane
-   DB is never ours. No foreign keys into control-plane tables; cross-refs
-   (`tenant_id`, `principal_id`) are plain `text`.
+2. **One Postgres connection, own schema.** Pass `memory.databaseUrl` (or env
+   `DATABASE_URL`; deprecated alias `KNOWLEDGE_DATABASE_URL`). Tables live under
+   the **`memory`** schema — never `public`. Cross-refs (`tenant_id`,
+   `principal_id`) are plain `text` (no FKs into control-plane tables). Same
+   Postgres instance as the host is fine; schema isolation is the boundary.
 3. **Never embed in-process.** Embedding/reranking are outbound HTTP calls to
    configured endpoints. A model endpoint is a trusted URL, same as the
    database URL — no self-host flags, no SSRF filtering here.

ARCHITECTURE.md

@@ -9,7 +9,8 @@ plane and the protected routes that read and write it.
 The store was detachable from a larger backend, then mountable:
 
 - No memory table has a foreign key into any control-plane table — cross-refs
-  (`tenant_id`, `principal_id`, source refs) are plain `text`.
+  (`tenant_id`, `principal_id`, source refs) are plain `text`. Tables live in
+  the **`memory`** schema (same Postgres URL as the host is fine).
 - Embedding and reranking go out as plain HTTP to configured model endpoints.
 - Document access is Interchange grant tags on the row (`accessTags` + creator),
   not a private ACL engine inside this package.
@@ -32,8 +33,9 @@ config (or an injected store).
 
 ## Boundaries
 
-- **Runtime**: Bun + Hono, mounted on the host app. **DB**: own pgvector
-  Postgres (`KNOWLEDGE_DATABASE_URL`) unless `documentStore` is injected.
+- **Runtime**: Bun + Hono, mounted on the host app. **DB**: Postgres via
+  passed `databaseUrl` / `DATABASE_URL` (`memory.*` schema) unless
+  `documentStore` is injected.
   **Types**: arktype at every route boundary.
 - **No auth of its own.** Interchange resolves the caller and puts `principal`
   + `tenant` on context; routes read identity from there

CHANGELOG.md

@@ -7,14 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Added
+### Changed
 
+- **Breaking:** Postgres schema renamed from `knowledge` to **`memory`**. Fresh
+  installs only — drop/recreate the old schema (or rename) on existing DBs.
+  Citation `open.type` is now `"memory"`.
+- **Breaking:** env `KNOWLEDGE_DATABASE_URL` is no longer required. Prefer
+  `DATABASE_URL` or pass `memory.databaseUrl` on config.
+  `KNOWLEDGE_DATABASE_URL` remains a deprecated alias.
 - Interchange `defineTool` factories at `@corbits/memory/tools` (`memory_add`,
   `memory_search`, `memory_list`) — HTTP clients for mounted hub routes with
   install env `memoryBaseUrl` / `memoryTenantId` / `memoryAuthToken`. Declared
   via `package.json` `interchange.tools` and `exports["./tools"]`.
 
-### Changed
+### Previously
 
 - **Breaking:** package and public surface renamed from `@corbits/knowledge-engine`
   to `@corbits/memory`. Public APIs: `createMemory` (optional `app` registers HTTP),
@@ -24,7 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `MemoryConfig`, `MemoryError`. HTTP paths are under
   `/api/tenants/:tenantId/memory/`; grants are
   `memory:add` / `memory:search`; access tags use `memory.owner:` / `memory.tenant:`
-  / `memory.space:`. Postgres schema name remains `knowledge`.
+  / `memory.space:`.
 - **Breaking:** memory plane surface is `add` / `search` / `list` with
   `principalId` + `tenantId` only. Inference is host-owned (no answer endpoint
   or personal-memory side-channel on the plane).

IMPLEMENTATION.md

@@ -24,7 +24,7 @@ src/
     deps.ts               # RouteDeps, caller(c) (context identity), grantGuard
     add.ts, search.ts, list.ts
   db/
-    schema.ts             # Drizzle table defs (knowledge.* schema)
+    schema.ts             # Drizzle table defs (memory.* schema)
     client.ts             # createDb(config) -> { db (drizzle), sql (raw postgres-js) }
   services/
     capture.ts            # captureDocument, deriveFromRawCapture — the write path
@@ -75,7 +75,9 @@ fallback)` parses a positive integer or throws.
 
 | Var | Required? | Default | Notes |
 |---|---|---|---|
-|  `KNOWLEDGE_DATABASE_URL` | **yes** | — | the engine's own pgvector Postgres |
+|  `DATABASE_URL` | **yes*** | — | Postgres for the memory plane (`memory.*` schema). Same DB as host is fine. |
+|  `KNOWLEDGE_DATABASE_URL` | no | — | **Deprecated** alias for `DATABASE_URL` |
+
 | `DB_POOL_MAX` | no | `8` | postgres-js pool size |
 | `FTS_LANGUAGE` | no | `english` | text search config for the lexical channel; fixed into the generated column at migration time — changing it later requires rebuilding the column (recipe below), and `runMemoryMigrations` fails loudly if config and column disagree. Unqualified `pg_catalog` config names only — a schema-qualified config (`myschema.mycfg`) is rejected explicitly, both when configuring and when read back from an already-migrated column. |
 | `EMBED_BASE_URL` | **yes** | — | embed endpoint root, no path suffix |
@@ -207,7 +209,7 @@ migration CHECK sets match the TS constants.
 
 ### Provenance and lineage (claim-bearing substrate)
 
-Two axes on `knowledge.version`, orthogonal to ranking priors:
+Two axes on `memory.version`, orthogonal to ranking priors:
 
 | Column / field | Values | Meaning |
 | --- | --- | --- |
@@ -220,7 +222,7 @@ A derived claim is a normal version with `provenance: inferred`, `lineageClass:
 
 ### Temporal model
 
-See `docs/TEMPORAL.md`. On `knowledge.version`:
+See `docs/TEMPORAL.md`. On `memory.version`:
 
 | Column | Role |
 | --- | --- |
@@ -471,7 +473,7 @@ search); otherwise it throws `MemorySearchInputError` (400).
     entity edges; `toHit` builds the wire `SearchHit` (citation/open-target
     resolution via `openTarget`, mapping known adapters — `artifact`, `task`,
     `workflow_run`, `mail` — to a deep-linkable `{type, id}`, else a generic
-    `{type: "knowledge", id: documentId}`).
+    `{type: "memory", id: documentId}`).
 11. **Evidence** — `deriveHybridEvidence`: `"none"` if zero hits; `"weak"` if
     the lexical channel contributed zero rows (a dense-only result never
     reports `"strong"`); otherwise `deriveEvidence` on the lexical rows —
@@ -599,7 +601,7 @@ Document access is Interchange authz — **not** a mini-ACL.
 
 - Write path: `resolveAccessTags` always writes `memory.owner:<caller>` and
   merges optional `accessTags` / share sugar (`tenant`, peer `principals`,
-  explicit `tags`). Stored on `knowledge.document.access_tags`.
+  explicit `tags`). Stored on `memory.document.access_tags`.
 - Read path (search + list): `canAccessDocument` — creator always allowed;
   otherwise `authorize(grantStore, principal, tenant, tag, "search")` for any
   tag on the document.
@@ -625,15 +627,15 @@ docker compose up -d                                   # pgvector + Ollama + rer
 docker compose exec ollama ollama pull nomic-embed-text
 cp .env.example .env
 bun install
-bun run db:setup                                       # apply the knowledge schema, idempotent
+bun run db:setup                                       # apply the memory schema, idempotent
 bun run test                                           # unit suite (no external services)
 ```
 
 `compose.yml` provisions the pgvector Postgres (`knowledge` db, host port
 `5434`), an Ollama embeddings server (`:11434`), and a TEI reranker (`:8085`).
 The engine **never embeds internally** — `EMBED_BASE_URL` must point at a real
 endpoint. A model endpoint is just a URL + capability options, trusted the same
-as `KNOWLEDGE_DATABASE_URL`:
+as `DATABASE_URL`:
 
 - **Local default**: Ollama at `http://localhost:11434`
   (`EMBED_API_STYLE=ollama`, `EMBED_MODEL=nomic-embed-text`).

PRODUCT.md

@@ -77,8 +77,9 @@ stores, Linear tools. Core never imports vendor SDKs.
 - No answer/generation endpoint — host owns inference.
 - Workbench is a client, not required.
 
-**Default durable store:** Postgres via `KNOWLEDGE_DATABASE_URL` only (no
-`DATABASE_URL` fallback), tables under the **`knowledge`** schema. When
+**Default durable store:** Postgres via `DATABASE_URL` (or passed
+`memory.databaseUrl`; deprecated alias `KNOWLEDGE_DATABASE_URL`), tables under
+the **`memory`** schema. When
 `documentStore` is injected, Postgres is not opened. Cross-refs are plain
 `text` — no FKs into the host control plane.
 

README.md

@@ -33,7 +33,8 @@ import { createMemory, loadMemoryConfig } from "@corbits/memory";
 
 const memory = createMemory({
   app,
-  config: loadMemoryConfig(), // KNOWLEDGE_DATABASE_URL + embed env
+  config: loadMemoryConfig(), // DATABASE_URL + embed env
+
   grantStore,
   conditionRegistry,
 });
@@ -124,11 +125,12 @@ always sees their own docs. Details:
 ## Config
 
 `loadMemoryConfig()` reads env (see `.env.example`). For the default pgvector
-store you need `KNOWLEDGE_DATABASE_URL`, `EMBED_BASE_URL`, `EMBED_MODEL`.
+store you need `DATABASE_URL`, `EMBED_BASE_URL`, `EMBED_MODEL`.
 
 ```ts
 import { runMemoryMigrations } from "@corbits/memory/migrations";
-await runMemoryMigrations(process.env.KNOWLEDGE_DATABASE_URL!);
+await runMemoryMigrations(process.env.DATABASE_URL!);
+
 ```
 
 Inject `documentStore` to use fakes, a host store, or a sibling adapter instead

docs/TEMPORAL.md

@@ -1,6 +1,6 @@
 # Temporal model
 
-How `knowledge.version` times and ranking classes work. Implementation lives
+How `memory.version` times and ranking classes work. Implementation lives
 in capture (write), hybrid-search (rank), and search/timeline (query filters).
 
 ## Four times (two stored, two derived)

migrations/0001_extensions.sql

@@ -1,5 +1,5 @@
--- Knowledge plane owns its own Postgres schema. Never pollutes public.
-CREATE SCHEMA IF NOT EXISTS "knowledge";
+-- Memory plane owns its own Postgres schema. Never pollutes public.
+CREATE SCHEMA IF NOT EXISTS "memory";
 
 -- pgvector for dense embeddings (cosine distance / HNSW).
 CREATE EXTENSION IF NOT EXISTS vector;

migrations/0002_knowledge_baseline.sql

@@ -1,7 +1,7 @@
 -- Single baseline for the knowledge plane (grant-tag authz from day one).
 -- Document access is access_tags + creator post-filter; no visibility_* columns.
 
-CREATE TABLE IF NOT EXISTS "knowledge"."document" (
+CREATE TABLE IF NOT EXISTS "memory"."document" (
   "id" text PRIMARY KEY,
   "tenant_id" text NOT NULL,
   "kind" text NOT NULL,
@@ -15,9 +15,9 @@ CREATE TABLE IF NOT EXISTS "knowledge"."document" (
 );
 
 CREATE UNIQUE INDEX IF NOT EXISTS "document_tenant_adapter_external_ref_uniq"
-  ON "knowledge"."document" ("tenant_id", "adapter", "external_ref");
+  ON "memory"."document" ("tenant_id", "adapter", "external_ref");
 
-CREATE TABLE IF NOT EXISTS "knowledge"."raw_capture" (
+CREATE TABLE IF NOT EXISTS "memory"."raw_capture" (
   "id" text PRIMARY KEY,
   "tenant_id" text NOT NULL,
   "adapter" text NOT NULL,
@@ -31,15 +31,15 @@ CREATE TABLE IF NOT EXISTS "knowledge"."raw_capture" (
 );
 
 CREATE UNIQUE INDEX IF NOT EXISTS "raw_capture_tenant_source_hash_uniq"
-  ON "knowledge"."raw_capture" ("tenant_id", "source_hash");
+  ON "memory"."raw_capture" ("tenant_id", "source_hash");
 
 CREATE INDEX IF NOT EXISTS "raw_capture_tenant_adapter_external_ref_idx"
-  ON "knowledge"."raw_capture" ("tenant_id", "adapter", "external_ref");
+  ON "memory"."raw_capture" ("tenant_id", "adapter", "external_ref");
 
-CREATE TABLE IF NOT EXISTS "knowledge"."version" (
+CREATE TABLE IF NOT EXISTS "memory"."version" (
   "id" text PRIMARY KEY,
   "tenant_id" text NOT NULL,
-  "document_id" text NOT NULL REFERENCES "knowledge"."document" ("id") ON DELETE CASCADE,
+  "document_id" text NOT NULL REFERENCES "memory"."document" ("id") ON DELETE CASCADE,
   "version" integer NOT NULL,
   "supersedes_version_id" text,
   "status" text NOT NULL DEFAULT 'active',
@@ -55,7 +55,7 @@ CREATE TABLE IF NOT EXISTS "knowledge"."version" (
   "actor_count" integer NOT NULL DEFAULT 1,
   "has_social_signal" boolean NOT NULL DEFAULT false,
   "source_class" text NOT NULL DEFAULT 'native',
-  "raw_capture_id" text REFERENCES "knowledge"."raw_capture" ("id"),
+  "raw_capture_id" text REFERENCES "memory"."raw_capture" ("id"),
   "generation" text NOT NULL DEFAULT 'live',
   CONSTRAINT "version_status_check"
     CHECK ("status" IN ('active', 'superseded', 'deprecated', 'archived', 'tombstoned')),
@@ -66,35 +66,35 @@ CREATE TABLE IF NOT EXISTS "knowledge"."version" (
 );
 
 CREATE UNIQUE INDEX IF NOT EXISTS "version_document_generation_version_uniq"
-  ON "knowledge"."version" ("document_id", "generation", "version");
+  ON "memory"."version" ("document_id", "generation", "version");
 
 CREATE INDEX IF NOT EXISTS "version_document_status_idx"
-  ON "knowledge"."version" ("document_id", "status");
+  ON "memory"."version" ("document_id", "status");
 
-CREATE TABLE IF NOT EXISTS "knowledge"."chunk" (
+CREATE TABLE IF NOT EXISTS "memory"."chunk" (
   "id" text PRIMARY KEY,
   "tenant_id" text NOT NULL,
-  "version_id" text NOT NULL REFERENCES "knowledge"."version" ("id") ON DELETE CASCADE,
-  "document_id" text NOT NULL REFERENCES "knowledge"."document" ("id") ON DELETE CASCADE,
+  "version_id" text NOT NULL REFERENCES "memory"."version" ("id") ON DELETE CASCADE,
+  "document_id" text NOT NULL REFERENCES "memory"."document" ("id") ON DELETE CASCADE,
   "ordinal" integer NOT NULL,
   "text" text NOT NULL,
   "role" text,
   "created_at" timestamp NOT NULL DEFAULT now()
 );
 
 CREATE UNIQUE INDEX IF NOT EXISTS "chunk_version_ordinal_uniq"
-  ON "knowledge"."chunk" ("version_id", "ordinal");
+  ON "memory"."chunk" ("version_id", "ordinal");
 
 -- {{FTS_LANGUAGE}} is substituted by runKnowledgeMigrations from FTS_LANGUAGE
 -- (or opts.ftsLanguage). Must match the language used at query time.
-ALTER TABLE "knowledge"."chunk"
+ALTER TABLE "memory"."chunk"
   ADD COLUMN IF NOT EXISTS "text_fts" tsvector
   GENERATED ALWAYS AS (to_tsvector('{{FTS_LANGUAGE}}', "text")) STORED;
 
 CREATE INDEX IF NOT EXISTS "chunk_text_fts_idx"
-  ON "knowledge"."chunk" USING GIN ("text_fts");
+  ON "memory"."chunk" USING GIN ("text_fts");
 
-CREATE TABLE IF NOT EXISTS "knowledge"."entity" (
+CREATE TABLE IF NOT EXISTS "memory"."entity" (
   "id" text PRIMARY KEY,
   "tenant_id" text NOT NULL,
   "kind" text NOT NULL,
@@ -104,9 +104,9 @@ CREATE TABLE IF NOT EXISTS "knowledge"."entity" (
 );
 
 CREATE INDEX IF NOT EXISTS "entity_tenant_kind_idx"
-  ON "knowledge"."entity" ("tenant_id", "kind");
+  ON "memory"."entity" ("tenant_id", "kind");
 
-CREATE TABLE IF NOT EXISTS "knowledge"."edge" (
+CREATE TABLE IF NOT EXISTS "memory"."edge" (
   "id" text PRIMARY KEY,
   "tenant_id" text NOT NULL,
   "rel" text NOT NULL,
@@ -127,12 +127,12 @@ CREATE TABLE IF NOT EXISTS "knowledge"."edge" (
 );
 
 CREATE INDEX IF NOT EXISTS "edge_from_idx"
-  ON "knowledge"."edge" ("tenant_id", "from_type", "from_ref");
+  ON "memory"."edge" ("tenant_id", "from_type", "from_ref");
 
 CREATE INDEX IF NOT EXISTS "edge_to_idx"
-  ON "knowledge"."edge" ("tenant_id", "to_type", "to_ref");
+  ON "memory"."edge" ("tenant_id", "to_type", "to_ref");
 
-CREATE TABLE IF NOT EXISTS "knowledge"."embed_model" (
+CREATE TABLE IF NOT EXISTS "memory"."embed_model" (
   "id" text PRIMARY KEY,
   "tenant_id" text NOT NULL,
   "model_key" text NOT NULL,
@@ -145,7 +145,7 @@ CREATE TABLE IF NOT EXISTS "knowledge"."embed_model" (
     CHECK ("status" IN ('active', 'retired'))
 );
 
-CREATE TABLE IF NOT EXISTS "knowledge"."transform_config" (
+CREATE TABLE IF NOT EXISTS "memory"."transform_config" (
   "id" text PRIMARY KEY,
   "tenant_id" text NOT NULL,
   "name" text NOT NULL,
@@ -156,10 +156,10 @@ CREATE TABLE IF NOT EXISTS "knowledge"."transform_config" (
     UNIQUE ("tenant_id", "name", "version")
 );
 
-CREATE TABLE IF NOT EXISTS "knowledge"."transform_run" (
+CREATE TABLE IF NOT EXISTS "memory"."transform_run" (
   "id" text PRIMARY KEY,
   "tenant_id" text NOT NULL,
-  "config_id" text NOT NULL REFERENCES "knowledge"."transform_config" ("id"),
+  "config_id" text NOT NULL REFERENCES "memory"."transform_config" ("id"),
   "scope" jsonb NOT NULL DEFAULT '{}',
   "generation" text NOT NULL,
   "status" text NOT NULL DEFAULT 'running',
@@ -173,7 +173,7 @@ CREATE TABLE IF NOT EXISTS "knowledge"."transform_run" (
 );
 
 CREATE UNIQUE INDEX IF NOT EXISTS "transform_run_generation_uniq"
-  ON "knowledge"."transform_run" ("generation");
+  ON "memory"."transform_run" ("generation");
 
 CREATE INDEX IF NOT EXISTS "transform_run_tenant_config_idx"
-  ON "knowledge"."transform_run" ("tenant_id", "config_id");
+  ON "memory"."transform_run" ("tenant_id", "config_id");

migrations/0003_claim_bearing.sql

@@ -2,12 +2,12 @@
 -- Edge rel / ref-type CHECKs already match the canonical set in 0002;
 -- this migration only adds how-content-was-obtained (stated vs inferred).
 
-ALTER TABLE "knowledge"."version"
+ALTER TABLE "memory"."version"
   ADD COLUMN IF NOT EXISTS "provenance" text NOT NULL DEFAULT 'unknown';
 
-ALTER TABLE "knowledge"."version"
+ALTER TABLE "memory"."version"
   DROP CONSTRAINT IF EXISTS "version_provenance_check";
 
-ALTER TABLE "knowledge"."version"
+ALTER TABLE "memory"."version"
   ADD CONSTRAINT "version_provenance_check"
     CHECK ("provenance" IN ('stated', 'inferred', 'unknown'));