[upstream PR 679] feat: add memory metacognition foundation

[wbugitlab1]

Source: Source pull request number: 679 in rohitg00/agentmemory (URL omitted to avoid GitHub cross-reference)
Title: feat: add memory metacognition foundation
Author: RayShark
State: open
Draft: no
Merged: no
Head: RayShark/agentmemory:feat/hermes-memory-fusion @ f6e66a7
Base: main @ 26980a8
Labels: (none)
Changed files: 0
Commits: 0
Created: 2026-05-27T15:01:19Z
Updated: 2026-05-27T15:08:45Z
Closed: (not closed)
Merged at: (not merged)

Original PR body:

Summary

• Add Phase 1 memory metacognition state, policy functions, and deterministic policy query expansion.
• Add shadow-first write candidates plus readback verification without automatic durable writes.
• Expose 8 authenticated REST endpoints for policy, write candidates, and readback; update REST endpoint counts to 132.

Scope notes

• No MCP tools are added in this phase.
• Policy suggestions remain deferred to Phase 2.
• Shadow candidate approval only changes candidate status; it does not call mem::remember.

Related

• Related to Hermes integration context in #107.
• Related Hermes follow-ups: #465 and #665.
• Inspired by RayShark/hermes-patches memory metacognition and shadow write pipeline.

Testing

• npm test -- test/api-memory-metacognition.test.ts test/consistency.test.ts test/memory-policy.test.ts test/memory-policy-types.test.ts test/write-candidates.test.ts test/readback.test.ts
• npm run build
• env HOME="$(mktemp -d)" npm test (113 files, 1192 tests)
• git diff --check

Summary by CodeRabbit

• New Features

  • Memory policy management system with query expansion and preflight rules
  • Write candidate generation pipeline for intelligent memory suggestions
  • Readback verification to validate memory retrieval accuracy
  • Eight new REST API endpoints for policy, write-candidate, and readback workflows

• Documentation

  • Updated API endpoint count from 124 to 132
  • Added Memory Metacognition implementation roadmap

Local branch:
Fork PR:
Fork decision:
Verification:
Notes:

[wbugitlab1]

Implemented and merged the minimal foundation slice in #1002.

Landed on main via merge commit 1da3373f:

• internal memory policy state/types
• mem::policy-get, mem::policy-update, and deterministic mem::policy-expand-query
• focused unit/type coverage for defaults, normalization, partial updates, timestamp stability, project scoping, disabled rules, caps, and invalid inputs

Verification before merge:

• corepack pnpm exec vitest run test/memory-policy-types.test.ts test/memory-policy.test.ts --exclude test/integration.test.ts
• corepack pnpm test
• corepack pnpm run build
• corepack pnpm run lint
• git diff --check origin/main...HEAD
• semgrep scan --config p/default --error --metrics=off .
• gitleaks detect --source . --redact --no-git
• GitHub CI: test (ubuntu-latest, 22) and test (macos-latest, 22) passed on feat: add memory policy foundation #1002

Leaving this issue open because the upstream PR body also describes write candidates, readback verification, and authenticated REST endpoints. Those were intentionally not included in this slice: the current repo has diverged from the upstream endpoint-count assumptions, and adding new externally consumed REST API surface requires a separate explicit approval/scope decision.

[wbugitlab1]

Closing this upstream tracker as not planned for this batch.

What landed:

• feat: add memory policy foundation #1002 implemented and merged the valid minimal foundation slice on main via merge commit 1da3373f.
• The slice added internal memory policy state/types plus mem::policy-get, mem::policy-update, and deterministic mem::policy-expand-query.
• Local verification and GitHub CI passed before merge.

Why the rest is not planned here:

• The remaining upstream PR scope includes shadow write candidates, readback verification, and eight authenticated REST endpoints.
• Those endpoints are externally consumed API surface. Repo instructions require explicit current-turn approval before changing documented or externally consumed APIs/system boundaries.
• The upstream endpoint-count assumptions are stale for this repo: upstream described moving from 124 to 132 endpoints, while this repo was already at a different REST surface before feat: add memory policy foundation #1002.
• Keeping all of those architectural/API additions inside one imported batch issue is too broad for the available approval gates.

Follow-up should be split into separate, explicitly approved issues for write candidates, readback verification, and any REST/API exposure.