{"id":50658557,"url":"https://github.com/maludb/maludb-core","last_synced_at":"2026-06-08T01:05:31.891Z","repository":{"id":358128167,"uuid":"1240023645","full_name":"maludb/maludb-core","owner":"maludb","description":"A memory DBMS for long-term institutional memory, human-AI knowledge sharing, and contextual recall. PostgreSQL 17 extension.","archived":false,"fork":false,"pushed_at":"2026-06-01T01:40:42.000Z","size":4601,"stargazers_count":3,"open_issues_count":2,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T03:22:16.262Z","etag":null,"topics":["database","memory","postgresql","postgresql-extension"],"latest_commit_sha":null,"homepage":"https://maludb.org","language":"PLpgSQL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maludb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-15T17:30:09.000Z","updated_at":"2026-06-01T01:40:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maludb/maludb-core","commit_stats":null,"previous_names":["maludb/maludb-core"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/maludb/maludb-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maludb%2Fmaludb-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maludb%2Fmaludb-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maludb%2Fmaludb-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maludb%2Fmaludb-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maludb","download_url":"https://codeload.github.com/maludb/maludb-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maludb%2Fmaludb-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34043826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-07T02:00:07.652Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","memory","postgresql","postgresql-extension"],"created_at":"2026-06-08T01:05:31.791Z","updated_at":"2026-06-08T01:05:31.885Z","avatar_url":"https://github.com/maludb.png","language":"PLpgSQL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MaluDB\n\nMaluDB is a memory DBMS for long-term institutional memory, human-AI\nknowledge sharing, and contextual recall. Built in **C** as PostgreSQL\nextensions on **Ubuntu 24.04 LTS**, with **PostgreSQL 17** (PGDG) as\nthe foundation.\n\nThe project is a single managed installation: `sudo apt install maludb`\n(forthcoming) gives you PostgreSQL 17 + pgvector + pgaudit + pg_partman\n+ the `maludb_core` extension wired together. Operators don't have to\nprovision PostgreSQL manually.\n\n## Status\n\n| | |\n|---|---|\n| Version | **0.95.0** (extension) — the \"semantic spine\": subjects/verbs/edges are the vector layer (deterministic in-DB entity cards + trigger-fed dirty queue + external embed worker, landing in the object-embedding rail) with **opt-in** `similar_to` traversal jumps; the chunk-compartment rail is frozen/deprecated; extraction JSON contract unchanged (see `docs/semantic-entity-embeddings.md`). Includes 0.94.0: episodes folded into subjects (**BREAKING** ingest contract — `episodes[]` removed; events are `subjects[]` entries with `occurred_at`). Latest release tag `v4.3.0` shipped extension 0.95.0 on 2026-06-07. V4 acceptance suite: `scripts/maludb-fieldtest-v4` walks every V4 surface end-to-end; `bench/v4/run-bench` publishes recall + latency baselines; `docs/v4/acceptance-matrix.md` maps plan §12 criteria to test artefacts. |\n| Test suite | **89 pg_regress targets** on PG 17 plus restd, realtimed, CLI, libmaludb v0.2, and pageindexd parser smoke checks |\n| Drivers | Python, Node.js, PHP, C — all four validated against the live extension |\n| External services | `maludb_modeld` (model gateway) + `maludb_mc2dbd` (database MCP listener) + `mcp-broker` (external-tool MCP broker) + `maludb-restd` (V3 REST gateway) + `maludb-realtimed` (V3 SSE event stream) + `maludb-pageindexd` (V4 PageIndex / ChatIndex builder) |\n| Roadmap | `requirements.md` §9 Stages 1–16+ shipped through V4 GA — see [`version4-pageindex-plan.md`](version4-pageindex-plan.md) |\n| Stage | Stages 1–15 (V3 GA + v3.1.0 follow-up) and Stage 16+ (V4 PageIndex / ChatIndex) shipped |\n| License | PostgreSQL License (BSD-style) |\n| Platforms | Ubuntu 24.04 LTS, x86_64 + arm64 |\n\n## What's in it\n\n| Capability | Where |\n|---|---|\n| Source → claim → fact → episode/memory pipeline | Stage 2 |\n| Bitemporal time (valid + transaction time) | Stage 3 (S3-1) |\n| Temporal supersession (corrections never overwrite) | Stage 3 (S3-2) |\n| SVPOR organization registries | Stage 3 (S3-3) |\n| MAUT confidence scoring | Stage 3 (S3-4) |\n| Lifecycle + decay + legal hold | Stage 3 (S3-5) |\n| Recursive-CTE graph traversal | Stage 4 (S4-1) |\n| FTS + pg_trgm fuzzy matching | Stage 4 (S4-2) |\n| Retrieval planner + query hints | Stage 4 (S4-3, S4-4) |\n| Authorization-aware retrieval (3-stage authz) | Stage 4 (S4-5) |\n| Workflow Extraction Engine | Stage 5 (S5-1) |\n| Skill Runtime as governed state machine | Stage 5 (S5-2) |\n| Skill discovery: manual subject / verb / keyword search, public skills, find/get/fork APIs | Stage 5 (S5-2) |\n| User onboarding roles: `GRANT maludb_user TO role`, read/admin variants, and guarded `GRANT maludb TO role` alias | Stage 5 (S5-2) |\n| Active Memory Pool manager | Stage 5 (S5-3) |\n| Episode replay API | Stage 5 (S5-4) |\n| Local Node sync protocol | Stage 6 (S6-1) |\n| Model Registry blue-green + dual-space routing | Stage 6 (S6-2) |\n| Embedding adapters + capability negotiation | Stage 6 (S6-3) |\n| Advanced MC2DB tools | Stage 6 (S6-4) |\n| External MCP broker (reference impl) | Stage 6 (S6-5) |\n| C / Python / Node.js / PHP SDKs | Stage 6 (S6-6) |\n\n## Doctrine\n\nA small number of invariants run through the whole system:\n\n1. **Corrections never silently overwrite history.** Supersession\n   closes a valid window and opens a new version with an explicit\n   supersession edge (`malu$supersession_edge`).\n2. **Provenance is mandatory.** Every derived object has a\n   `malu$derivation_ledger` entry. No row appears without one.\n3. **Authorization is checked at three points** — planning,\n   expansion, assembly. Never only at the final answer.\n4. **Multi-model writes are atomic.** A logical operation that\n   touches metadata, source links, graph edges, temporal windows,\n   FTS, vectors, workflows, and audit logs commits or aborts as one.\n5. **Nodes (local memory nodes) are never authoritative.** They\n   submit proposals; the server applies them under governance.\n6. **Workflow candidates don't auto-promote.** Approving a candidate\n   flips a status; it doesn't create a procedural memory by side\n   effect.\n\n## Quickstart\n\n```bash\n# 1. Install (Ubuntu 24.04 build host).\nsudo scripts/maludb-bootstrap\n\n# 2. Create a database and the extension.\nsudo -u postgres createdb mydb\nsudo -u postgres psql -d mydb -c \"CREATE EXTENSION maludb_core CASCADE\"\n\n# 3. VERIFY the version before going further. CREATE EXTENSION installs\n#    whatever default_version the host's extension files declare — if a\n#    stale build was ever installed on this host, you silently get an old\n#    version and later steps fail with \"relation ... does not exist\".\nsudo -u postgres psql -d mydb -tAc \"SELECT maludb_core.maludb_core_version()\"\n#    Expected: the version in maludb_core.control of the checkout you\n#    installed from (0.94.0 for this tree). If it prints something older:\n#      sudo make -C \u003cthis-checkout\u003e install\n#      sudo -u postgres psql -d mydb -c \"ALTER EXTENSION maludb_core UPDATE\"\n\n# 4. Walk through the first scenario.\npsql -d mydb -f examples/01-ingest-to-replay.sql\n```\n\n### Enable MaluDB memory in an application schema\n\nMaluDB does not modify ordinary PostgreSQL schemas automatically. To opt a\nschema into schema-local memory views:\n\n```sql\n-- Run this connected to the database where maludb_core is installed\n-- (e.g. `psql -d mydb` or `\\c mydb`). The extension is per-database:\n-- running this from the default `postgres` database fails with\n-- ERROR: schema \"maludb_core\" does not exist.\nCREATE USER zozocal;\nGRANT maludb_user TO zozocal;\nCREATE SCHEMA zozocal AUTHORIZATION zozocal;\nSET ROLE zozocal;\nSET search_path TO zozocal, maludb_core, public;\nSELECT * FROM maludb_core.enable_memory_schema();\nSELECT * FROM maludb_subject;\n```\n\nFor read-only users, grant `maludb_read`. On fresh installs where the role name\nis available, `GRANT maludb TO app_user` is also a short alias for\n`GRANT maludb_user TO app_user`. Existing operator installs that already have a\nlogin role named `maludb` keep using `maludb_user` to avoid privilege confusion.\n\n### Upgrade an existing installation\n\nUpgrading is three steps, and **all three are per-host / per-database /\nper-schema respectively** — stopping early leaves the system in a mixed state:\n\n```bash\n# 1. PER HOST: install the new extension files (from this checkout).\n#    Build/install ONLY from the current checkout — an old working tree\n#    `make install`s the same filenames and silently downgrades\n#    default_version for every future CREATE EXTENSION on the host.\ncd \u003cthis-checkout\u003e \u0026\u0026 git pull\nsudo make install PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config\n\n# 2. PER DATABASE: update the extension in every database that has it.\nsudo -u postgres psql -d mydb -c \"ALTER EXTENSION maludb_core UPDATE\"\nsudo -u postgres psql -d mydb -tAc \"SELECT maludb_core.maludb_core_version()\"  # confirm\n\n# 3. PER TENANT SCHEMA: refresh the memory facades. A migration cannot\n#    replace tenant-owned views/functions (they are not extension members),\n#    so new or changed facade objects only appear after this re-run.\nsudo -u postgres psql -d mydb -c \"SELECT * FROM maludb_core.enable_memory_schema('zozocal')\"\n```\n\nTo list the schemas that need step 3 in a database:\n\n```sql\nSELECT schema_name, enabled_version FROM maludb_core.malu$enabled_schema;\n```\n\nSchemas still showing the old `enabled_version` haven't been refreshed.\n`scripts/maludb-validate` checks that the installed extension version in the\ndatabase matches the version the host's extension files declare.\n\n### Connect from an application server\n\nA fresh install only accepts local connections. Four server-side changes\nare required before an application server on the same network can reach\nthe database; all four are needed — if any one is missing, the\nconnection fails.\n\n**1. Make PostgreSQL listen on the network.** This is the step that\nblocks everything else: Ubuntu's PostgreSQL 17 default is\n`listen_addresses = 'localhost'`, so remote clients get *connection\nrefused* regardless of any `pg_hba.conf` or firewall setup. Edit\n`/etc/postgresql/17/main/postgresql.conf`:\n\n```conf\nlisten_addresses = '*'        # or a specific address, e.g. '192.168.100.163'\n```\n\nA full restart is required — `reload` does not apply this setting:\n\n```bash\nsudo systemctl restart postgresql\nss -tln | grep 5432           # should now show 0.0.0.0:5432 (or your address)\n```\n\n**2. Give the application role a password.** Peer authentication does\nnot work over TCP; remote logins use `scram-sha-256`. The `zozocal`\nuser created above has no password yet:\n\n```bash\nsudo -u postgres psql -c \"ALTER USER zozocal PASSWORD 'choose-a-password'\"\n```\n\n**3. Allow the client in `pg_hba.conf`.** Add a `host` line to\n`/etc/postgresql/17/main/pg_hba.conf` for the application server's\naddress (or subnet), then reload:\n\n```conf\n# TYPE  DATABASE   USER      ADDRESS               METHOD\nhost    mydb       zozocal   192.168.100.0/24      scram-sha-256\n```\n\n```bash\nsudo systemctl reload postgresql\n```\n\n**4. If `ufw` is active, open `5432/tcp` to the client subnet.** The\n[hardening guide](docs/post-install-hardening.md) only opens `5329/tcp`\n(the MC2DB listener); database connections need their own rule:\n\n```bash\nsudo ufw allow from 192.168.100.0/24 to any port 5432 proto tcp\n```\n\n**Verify from the application server** before wiring up a driver:\n\n```bash\nPGPASSWORD='choose-a-password' psql -h \u003cserver-address\u003e -p 5432 -U zozocal -d mydb \\\n    -c 'select current_user, current_database()'\n```\n\nTo expose the MC2DB listener (`:5329`) to the network as well, set\n`HOST=0.0.0.0` together with TLS and a bearer token — see\n[docs/install.md](docs/install.md) §6 and\n[docs/post-install-hardening.md](docs/post-install-hardening.md).\n\nThe detailed install playbook is in [docs/install.md](docs/install.md).\nA first-time tutorial is in [docs/getting-started.md](docs/getting-started.md).\nDay-2 operations are in [docs/admin-guide.md](docs/admin-guide.md).\n\nPHP applications can install the published Composer package directly:\n\n```bash\ncomposer require maludb/client:^0.1\n```\n\nIf Composer reports that ZIP extraction tools are missing, install\n`unzip` or `7z` first. On Ubuntu:\n\n```bash\nsudo apt install unzip\n```\n\nSee [drivers/php/README.md](drivers/php/README.md) for connection setup,\nautoloading notes, examples, and smoke-test instructions.\n\n## Documents\n\n- [`requirements.md`](requirements.md) — what the system must satisfy.\n- [`version4-pageindex-plan.md`](version4-pageindex-plan.md) — Version 4 PageIndex / ChatIndex implementation plan.\n- [`docs/install.md`](docs/install.md) — operator-grade install playbook.\n- [`docs/getting-started.md`](docs/getting-started.md) — first-time walkthrough.\n- [`docs/admin-guide.md`](docs/admin-guide.md) — backups, audit queries, lifecycle.\n- [`docs/bench-baseline.md`](docs/bench-baseline.md) — performance baseline.\n- [`docs/security-review.md`](docs/security-review.md) — RLS / pgaudit / grants audit.\n- [`docs/runtime.md`](docs/runtime.md) — local model runtime details.\n- [`docs/monitoring.md`](docs/monitoring.md) — Prometheus integration.\n- [`docs/maludb-mc2dbd-contract.md`](docs/maludb-mc2dbd-contract.md) — MC2DB listener contract.\n- [`examples/`](examples/) — end-to-end SQL scenarios.\n\n## Stage roadmap\n\nThe project ships in stages (`requirements.md` §9):\n\n- **Stage 1** ✅ — PostgreSQL substrate + pgvector + packaging.\n- **Stage 1.5/1.6** ✅ — Model runtime + MC2DB listener (R1.0).\n- **Stage 1.7 (R1.1)** ✅ — Advanced vector substrate.\n- **Stage 2** ✅ — Memory object model.\n- **Stage 3** ✅ — Bitemporal, SVPOR, MAUT, lifecycle.\n- **Stage 4** ✅ — Retrieval planner, hybrid search, authz.\n- **Stage 5** ✅ — Workflow extraction, skill runtime, active pools, episode replay.\n- **Stage 6 (in-DB)** ✅ — Local node sync, model registry migration, advanced MC2DB tools.\n- **Stage 6 (broker)** ✅ — External MCP broker reference (`services/mcp-broker` v0.1.0).\n- **Stage 6 (drivers)** ✅ — C / Python / Node.js / PHP SDKs (v0.1.0 each). C SDK v0.2.0 (pool / skill / node wrappers) is a V3-SDK-01 follow-up.\n- **Stage 7** ✅ — Hardening: benchmarks, security review, docs, deb packaging, **public alpha tagged**.\n- **Stages 8–15 (Version 3)** ✅ — Platform-ergonomics track: identity/secrets, REST gateway + CLI + SDK parity, durable queue + cron, verbatim source archive v1, realtime + presence, vector/retrieval polish, metrics + log drains + backup/PITR + preview envs + replicas. Shipped as `v3.0.0` and `v3.1.0`.\n- **Stages 16+ (Version 4)** ✅ — PageIndex / ChatIndex as governed memory surfaces over the Verbatim Source Archive. Reachable through every external surface (SQL / MC2DB / REST / CLI / 4-language SDK). Shipped as `v4.0.0`. See [`version4-pageindex-plan.md`](version4-pageindex-plan.md).\n\n## Contributing\n\nSign-off (DCO) required on every commit. Commit messages start with\nthe imperative subject; the body explains the *why* and references\n`requirements.md` section numbers when implementing a specific\nrequirement.\n\nBranch naming:\n- `phase-N/\u003ctopic\u003e` for roadmap work\n- `fix/\u003ctopic\u003e` for fixes\n- `spike/\u003ctopic\u003e` for exploration\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaludb%2Fmaludb-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaludb%2Fmaludb-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaludb%2Fmaludb-core/lists"}