forked from molecule-ai/molecule-core
Hongming Wang
53d823e719
First of 11 PRs implementing the memory-system plugin refactor (RFC #2728). This PR is pure additive scaffolding — no behavior change, no integration yet. It defines the wire shape between workspace-server and a memory plugin so PR-2 (HTTP client) and PR-3 (built-in postgres plugin) can be built against a single source of truth. What ships: - docs/api-protocol/memory-plugin-v1.yaml: OpenAPI 3.0.3 spec covering /v1/health, namespace upsert/patch/delete, memory commit, search, forget. Auth-free (private network only); workspace-server is the only sanctioned client and the security perimeter. - workspace-server/internal/memory/contract: typed Go bindings with Validate() methods on every wire object so both client (PR-2) and server (PR-3) self-check at the boundary. - Round-trip JSON tests for every type (catch asymmetric tag bugs). - 5 golden vector files under testdata/ pinning the exact wire shape; update via UPDATE_GOLDENS=1. Coverage: 100% of statements in contract.go. The validation rules encode design decisions worth flagging in review: - SearchRequest with empty Namespaces is REJECTED at plugin level — workspace-server is required to intersect the readable set server-side; an empty list reaching the plugin is a bug. - NamespacePatch with no fields is REJECTED — empty patches are pointless round-trips. - MemoryWrite with whitespace-only Content is REJECTED — zero-info memories pollute search results. No code yet calls into this package; integration starts in PR-2.
docs/
This directory serves two purposes:
- Markdown content — everything under
architecture/,agent-runtime/,api-protocol/,development/,frontend/,plugins/,product/, etc. This is what agents and humans read. - VitePress site —
.vitepress/config.ts,package.json,package-lock.json. These drive the rendered documentation site.
Local preview
cd docs
npm install
npm run dev # preview on http://localhost:5173
npm run build # static build to docs/.vitepress/dist/
Conventions
- New top-level docs must be linked from
PLAN.md,README.md, andCLAUDE.md— otherwise agents can't find them (see.claude/memoryfeedback_cross_reference_docs.md). edit-history/YYYY-MM-DD.mdis append-only log of significant changes; don't rewrite history.archive/holds one-shot analyses and retired docs — kept for context but not maintained.
Why site tooling lives here (not in docs-site/)
VitePress expects its config at <root>/.vitepress/config.ts where <root> is also the content directory. Splitting tooling into a sibling docs-site/ would require a non-trivial srcDir shim and break relative links in .vitepress/config.ts. Keeping both together is the pragmatic choice; this README is the tradeoff ledger.