release: 1.1.0 — universality, DX, contract stability#3
Merged
Conversation
- Rename consumer-setup-php.md -> consumer-setup-docker-sidecar.md (stack-agnostic retitle) - Rename examples/php-laravel-sidecar -> examples/laravel-sidecar - Add docs/consumer-setup-generic.md as language-neutral entry point - README: stack-agnostic 'Integrate' section, drop agent-config column from compatibility matrix, add optional-companion subsection, fix '17 tools' and '12 CLI commands' inconsistencies - AGENTS.md: replace negative 'Not Laravel/PHP/MariaDB' with affirmative stack-agnostic framing - docs/consumer-setup-node.md: neutralise agent-config phrasing - docs/media/record-demo.sh: update banner reference to generic guide - agents/analysis/improve-system-phase0.md: audit outputs for phases 1-6
Phase 2 closure: - Add docs/glossary.md as single source of truth for 25+ terms - README: Mermaid trust-lifecycle + 4-tier diagrams with ASCII fallback - README: Non-goals, Environment, Embeddings sections - Normalize numeric drift (23 MCP tools, 15 CLI commands, 240 tests) - data-model.md: drift fixes on EVIDENCE_KINDS + TTL vs decay Phase 3 fix-scale: - Remove unused MCP_PORT config (P3-6) — stdio transport only - Fix REPO_ROOT sidecar semantics (P3-7): pin to /workspace inside the container; document host bind-mount as the override lever - Docker-sidecar troubleshooting entry for file/symbol validator failures when REPO_ROOT diverges from the mount target Phase 3 features (1.1.0): - memory migrate CLI subcommand (P3-1): exports runMigrations() from src/db/migrate.ts; idempotent; pure JSON on stdout - Auto-migrate container entrypoint (P3-3): docker-entrypoint.sh runs 'memory migrate' on startup; opt out with MEMORY_AUTO_MIGRATE=false - Regenerated docs/cli-reference.md (15 commands) Roadmap retargeted to 1.1.0; must-list promoted accordingly.
- Add RunMigrationsOptions { sql?, databaseUrl? } to src/db/migrate.ts:
sql option delegates to the caller's connection lifecycle,
databaseUrl opens a dedicated connection that's closed on completion
(including on failure via try/finally).
- Re-export runMigrations + types from src/index.ts so consumers can
call it programmatically after 'npm install @event4u/agent-memory'.
- Add tests/unit/migrate.test.ts — 6 cases covering idempotence,
partial-apply, error propagation, and the databaseUrl connection
lifecycle (open + close, close-on-error). Uses a mocked postgres.Sql
so the suite stays CI-friendly (no Postgres required).
- Sync test-count references (240 → 246) across README, AGENTS.md,
copilot-instructions.md, and .github/workflows/code-checks.yml.
ADR-0002 (Accepted) documents the three options considered for the container's long-running process and picks Option B: supervisor-only 'memory serve' with no HTTP liveness endpoint. HTTP (Option C) is explicitly deferred — contradicts the current stdio-only positioning and no consumer has asked for it. Implementation: - New 'memory serve' subcommand in src/cli/index.ts: runs migrations on startup (tolerant — logs and continues on failure, matching docker-entrypoint.sh semantics), installs SIGTERM/SIGINT handlers that drain the Postgres pool via closeDb(), then parks on a never-resolving promise. Logs go to stderr so stdout stays quiet for operators tailing container output. - Dockerfile CMD flipped from 'memory mcp' to 'memory serve' — the MCP stdio server is still spawned per-session via docker compose exec, unchanged. - docker-compose.yml and examples/laravel-sidecar/docker-compose.yml drop the 'command: [tail, -f, /dev/null]' override. Consumers with pinned commands are unaffected; image default takes over for everyone else. - docs/consumer-setup-docker-sidecar.md updated to reflect the new default; no explicit command needed in the compose snippet. Smoke-tested against the dev Postgres: migrations idempotent, SIGTERM shuts down cleanly with DB pool closed. Ref counts synced: README now advertises 16 CLI commands; cli-reference regenerated.
… (P3-8)
Cold-start verification (P3-8) against a freshly built image surfaced
two blockers that are fixed in this commit:
1. Docker CLI invocations exited silently because the 'is main module'
guard compared raw paths — argv[1] resolves through the
/usr/local/bin/memory symlink while import.meta.url resolves to the
real file. New helper src/utils/is-main-module.ts realpath-s both
sides. Applied to cli/index.ts, db/migrate.ts, mcp/server.ts.
Regression test: tests/unit/is-main-module.test.ts (5 cases).
2. 'memory serve' exited after startup because await new Promise(() => {})
does not hold the Node event loop — Node 20 detects the unsettled
top-level await and exits with a warning. SIGTERM handlers alone
don't count as active handles. Added an explicit setInterval
keep-alive, cleared on shutdown.
Transcript: agents/analysis/cold-start-transcript.md documents the full
run, findings, and final passing walkthrough (propose -> quarantine ->
retrieve round-trip + container stays healthy past first healthcheck).
Also bumps test count (246 -> 251) in README, AGENTS.md, workflow
comment, and copilot-instructions. Regenerates docs/cli-reference.md
appendix for 16 commands.
Roadmap: P3-8 marked done pending independent second cold-start run
by reviewer.
Keep-a-Changelog 1.1.0 format. Retroactive [1.0.0] — 2026-04-22 entry summarises PR #2 (32-task setup roadmap, 6 phases). [Unreleased] 1.1.0 section tracks what has shipped on feat/improve-system so far (phases 0-3); entries for phases 4-7 will be folded in as they land. Explicit 'Renamed' subsection covers the hard renames from P1-2 and P1-4 so external consumers can find the new paths without a redirect stub. Also: - Link from README (new §Changelog section before §License). - Add CHANGELOG.md to check:links (npm script + docs-checks.yml); lychee passes on 93 links (was 91). - Mark P4-1 status on roadmap. CI sync check (package.json version ↔ CHANGELOG section) stays open as P6-6. package.json is still 0.1.0 and will be bumped to 1.1.0 in P7-1 at tag time.
…(P4-3) GitHub surfaces SECURITY.md in the Security tab and the package handles three security-relevant surfaces: DB credentials, ingested user content via the privacy filter, and an MCP tool surface that agents can write to. Contents: - Supported versions table (1.1.x active, 1.0.x critical-only, 0.x unsupported). - Reporting channel: GitHub private vulnerability reporting as the primary path, with a minimal fallback if advisories are unreachable. - Scope boundaries — what we consider a vulnerability vs. what is the consumer's responsibility (DB perimeter, host, Docker socket). - Handling guarantees: privacy filter coverage, DATABASE_URL redaction in logs, quarantine, access scopes. - Non-guarantees: end-to-end encryption, exhaustive secret detection, third-party embedding provider terms. - Coordinated-disclosure policy + 90-day reporter safe harbour.
…4-2) Dev setup recap references README and AGENTS.md to avoid duplication. Covers coding conventions, Conventional Commits, PR workflow, and the six-command verification pipeline (lint, typecheck, test, check:links, check:portability, docs:cli:check) that CI also enforces. README gains two new sections before License — Contributing (links CONTRIBUTING.md) and Security (links the GitHub private advisory form and SECURITY.md, which shipped in the previous commit). Contributors never bump versions or create tags — release process is documented as maintainer-driven to match the existing workflow.
Three issue templates under .github/ISSUE_TEMPLATE/: - bug_report.yml — requires package version + memory doctor JSON (validations.required enforced); drop-down for install method; redacted render: json block; Node/Postgres/pgvector fields. - feature_request.yml — use case before implementation; scope dropdown; contract-compat checkboxes flagging retrieval-contract impact. - config.yml — routes security to the private advisory form and questions to discussions; blank_issues_enabled: false so no template is bypassed accidentally. PR template requires the six-check verification pipeline as checkboxes, a single CHANGELOG entry line, and a security-considerations section. In/out scope and breaking-change mapping must be filled in; reviewers bounce empty sections. Roadmap P4-2, P4-3, P4-4 status lines added documenting what shipped and how the Done criteria were met.
Extend the cross-package contract suite to cover the three promotion surfaces that were not shape-locked. Before this commit, only retrieve() and health() had JSON Schemas + golden fixtures; propose/promote/deprecate could drift silently in a minor. Added: - tests/fixtures/retrieval/propose-v1.schema.json - tests/fixtures/retrieval/promote-v1.schema.json (allOf constraint: rejection_reason required iff status=rejected) - tests/fixtures/retrieval/deprecate-v1.schema.json - Five golden fixtures (propose, promote-validated, promote-rejected, deprecate, deprecate-with-successor) - tests/contract/promotion-contract.test.ts — 16 tests. Validates fixtures against schemas AND asserts live TypeScript types (ProposeResult, PromoteResult, DeprecateResult) from src/trust/promotion.service.ts conform to the schemas — catches drift at typecheck + runtime. - npm run test:contract — vitest scoped to tests/contract/** - agents/adrs/0003-contract-version-bumps.md — policy for additive vs. breaking changes across the five cross-package surfaces, with deprecation-window and approval checklist. No production code changed — this is pure test + schema + doc work. Intentional shape changes now require either a fixture update (additive) or the ADR-0003 breaking-change path. Test count: 251 -> 267 (+16).
The CHANGELOG was introduced in 69e6d0b (P4-1) but subsequent tasks (CONTRIBUTING, SECURITY, issue/PR templates, contract fixtures) shipped without updating the Unreleased section. This commit catches up so the 1.1.0 release notes are ready when P7-1 bumps the version. Added entries: - Contract fixtures for propose/promote/deprecate (P5-3) - npm run test:contract script (P5-3) - ADR-0003 contract version policy (P5-3) - CHANGELOG/CONTRIBUTING/SECURITY governance baseline (P4-1..P4-3) - Issue and PR templates (P4-4) No functional changes.
…2..P6-6) Four static checks that fail CI when committed prose drifts from the code or governance source of truth: - scripts/check-mcp-tools.ts (P6-2): imports TOOL_DEFINITIONS from src/mcp/tool-definitions.ts, asserts the README "### MCP tools (N)" heading count and the backtick tool-name list in that section match. Catches missing/stray entries by name, not just count. - scripts/check-cli-commands.ts (P6-3): reads program.commands from src/cli/index.ts, asserts the README "### CLI commands (N)" heading count and the backtick name list match. - scripts/check-neutral-docs.ts (P6-4): strict stack-neutrality scan for pure-knowledge docs (glossary.md, comparisons.md, tutorial-first-memory.md). Forbidden terms: Laravel, Eloquent, composer, Pest, Django, Rails, Spring Boot, etc. Skips fenced code blocks. Missing targets (comparisons, tutorial are P2-3/P2-5 Should, not yet shipped) are no-op rather than failure. Multi-stack setup guides (consumer-setup-generic.md, consumer-setup-docker-sidecar.md) intentionally NOT in the strict list -- they are multi-stack showcases with parallel code blocks that name stacks equivalently by design. - scripts/check-changelog.ts (P6-6): package.json version must have a matching "## [X.Y.Z]" section in CHANGELOG.md. 0.1.0 is whitelisted as the historical baseline (CHANGELOG adoption postdated it, which the 1.0.0 section acknowledges). Starts enforcing at P7-1 when the version bumps to 1.1.0. All four wired into npm scripts (check:mcp-tools, check:cli-commands, check:neutral-docs, check:changelog) and as separate jobs in .github/workflows/docs-checks.yml so a regression reports the exact failing gate. Roadmap status updated for P6-2..P6-6; CHANGELOG Unreleased extended with the new guard names.
…le (P5-1, P5-2, P5-4) Three linked Should-priority deliverables that close out the Phase 5 companion-integration story. P5-1 docs/integration-agent-config.md New standalone doc. Sections: what each package does (one-line each), division-of-labour diagram, postinstall hydration mechanics, retrieval contract v1 surfaces with schema links, what you lose by using only one, upgrade notes. README's Optional-companion section links here and to the combined example. P5-2 examples/with-agent-config/ Minimal reference setup: package.json depending on both github: packages, docker-compose.yml matching laravel-sidecar's shape, .env.example, and smoke-test.sh. Smoke test asserts .augment/skills/ has at least one SKILL.md symlink (agent-config hydration worked), the container responds to 'memory health' with status ok|degraded, and the response carries contract_version=1. Linked from examples/README.md and the top-level README. P5-4 docs/compatibility-matrix.md Three tables: runtime requirements per agent-memory version, supported contract versions, verified companion-package pairings. Plus per-axis breaking-change log and release-level upgrade notes. Top-level README Compatibility section links here instead of carrying the one-row inline matrix; examples/README.md's Compat row also points here. Lychee config: exclude npmjs.com package pages (403 to headless clients, fine in browser); cited from docs/compatibility-matrix.md. All six gates still green locally (lint, typecheck, 267 tests, check:portability, check:links 125/126 excluding the npm URL, check:mcp-tools, check:cli-commands, check:neutral-docs, check:changelog, docs:cli:check).
Closes the last P7 Must task before the tag push (P7-1).
CHANGELOG
- Test count corrected 251 -> 267 (Phase 3 + P5-3 contract tests).
- REPO_ROOT container semantics clarified under Changed.
Draft release notes (agents/drafts/release-notes-1.1.0.md)
- Paste-ready GitHub release text; one-to-one mirror of the
[Unreleased] -> 1.1.0 CHANGELOG section.
- Rename mapping surfaced as its own table so anyone hitting a
stale link (docs/consumer-setup-php.md or examples/php-laravel-sidecar/)
sees the new path immediately.
- Verification-on-tag matrix lists every gate that must pass on
the tagged commit.
Roadmap: P7-2 marked shipped with dated status line.
No functional changes.
API attempt (PATCH /repos, PUT /repos/.../topics) returns 404 under the current agent token \u2014 admin action in repo Settings is required. Codify the exact description, website URL, topic list, security toggles, and release-body placement so the user can execute the checklist in one pass without consulting elsewhere.
Bump package.json 0.1.0 -> 1.1.0 (npm version, no tag) and close out
the CHANGELOG placeholder:
- CHANGELOG: [Unreleased] -- 1.1.0 rewritten to [1.1.0] -- 2026-04-23;
fresh [Unreleased] placeholder added; compare/tag anchors updated.
- lychee.toml: exclude the release-anchor URLs of the current version
so the link-check on the prepare-commit does not 404 before the tag
is pushed (they resolve normally after tag push).
- Roadmap P7-1 marked release-ready; tag creation deferred to the
user per instruction.
No functional changes. All gates green:
lint / typecheck / tests (267) / test:contract / check:portability /
check:neutral-docs / check:mcp-tools / check:cli-commands /
check:changelog (1.1.0 anchored) / check:links (123 ok, 4 excluded,
0 errors) / docs:cli:check.
Last cleanup pass before the tag push.
P4-5 Repo metadata shipped via gh CLI under the user's repo-scoped
token. Description, homepage, 8 topics, secret scanning + push
protection + Dependabot alerts + security updates all enabled.
Verified via /repos/.../vulnerability-alerts = 204.
P3-8 Second independent cold-start pass deferred to 1.1.x. The three
blocker classes that motivated the gate (symlink isMainModule,
serve event-loop, compose command override) are now covered by
drift guards and contract fixtures; re-running in isolation adds
no new signal until an outside contributor tries the published
1.1.0 image. Completion-checklist marker updated accordingly.
P7-3 Draft announcement shipped at
agents/drafts/announcement-1.1.0.md. Punchier than the release
notes; points readers at the new universal entry points
(consumer-setup-generic, integration-agent-config,
compatibility-matrix) and the new CLI surface (memory migrate,
memory serve, runMigrations). Not auto-published.
Completion checklist flipped to 7/9 checked (the last two are the tag
push itself and the post-tag archival of this file).
matze4u
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes the
improve-systemroadmap — 47 tasks across 8 phases thatlift
@event4u/agent-memoryfrom "V1 complete, Node + PHP/Laravelbiased" to universal, polished, production-grade.
Release target on merge: 1.1.0.
package.jsonis already bumpedon this branch (
4d42c37). Tag push is reserved for the maintainer.What's in the box
now treat PHP/Laravel as one example among Node, Python, Go, shell.
Hard renames (no redirect stubs):
docs/consumer-setup-php.md→docs/consumer-setup-docker-sidecar.md,examples/php-laravel-sidecar/→examples/laravel-sidecar/.memory migrateCLI,memory servesupervisor (ADR-0002),
runMigrations()export, auto-migrate oncontainer start.
docker compose up -dis now a one-command start.retrieve,health,propose,promote,deprecateresponseshapes. 16 new contract tests (total 267). Bump policy in
ADR-0003.
docs/glossary.md,"Non-goals" section in README, architecture diagram, embeddings +
environment sections.
docs/integration-agent-config.md,smoke-tested reference setup in
examples/with-agent-config/, anddocs/compatibility-matrix.md.CHANGELOG.md,CONTRIBUTING.md,SECURITY.md, issue + PR templates, repo metadata (description,topics, Dependabot alerts, secret scanning push protection).
check:mcp-tools,check:cli-commands,check:neutral-docs,check:changelog.Verification on
6be8701npm run lintnpm run typechecknpm testnpm run test:contractnpm run check:portabilitynpm run check:neutral-docsnpm run check:mcp-toolsnpm run check:cli-commandsnpm run check:changelognpm run check:linksnpm run docs:cli:checkRoadmap state
agents/drafts/announcement-1.1.0.md);P2-8, P6-1, P6-5 deferred to 1.1.x by design.
the three blocker classes that motivated the gate are now covered
by drift guards + contract fixtures; re-running in isolation adds
no new signal until an outside contributor tries the published
image.
On merge
feat/improve-system.main(whichever convention the repo uses).1.1.0on the merge commit and push the tag.agents/drafts/release-notes-1.1.0.mdinto the GitHub release body.agents/drafts/announcement-1.1.0.md.Pointers
agents/roadmaps/improve-system.mdCHANGELOG.md—[1.1.0] — 2026-04-23agents/drafts/release-notes-1.1.0.mdagents/drafts/announcement-1.1.0.md