From 479b3f4766d00e2915ba6c944be43b30ce07da5e Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 7 Sep 2026 04:45:47 +0000 Subject: [PATCH] docs: align application notes with published 0.19.5 honesty c Bump app-notes index and builder install to Hatch/PyPI memnet-llm==0.19.5. Teach SHAPE_DROP_KEYS (no hid/elementId/nickname id on shaped pin_map) and cue by labels+properties instead of copy-id / leftover --anchor. Co-authored-by: chouswei --- docs/application-notes/README.md | 9 +++--- .../inverting-amplifier-gql-case-study.md | 28 +++++++++---------- .../system/llm-build-on-memnet.md | 8 +++--- .../system/llm-system-dev-multitask.md | 2 +- 4 files changed, 24 insertions(+), 23 deletions(-) diff --git a/docs/application-notes/README.md b/docs/application-notes/README.md index 8641a96..e7d09f8 100644 --- a/docs/application-notes/README.md +++ b/docs/application-notes/README.md @@ -3,7 +3,7 @@ How to **use** MemNet (not engine internals). Folders: **system** (repos / SysML / builder), **domains** (worked domains), **examples** (InvAmp). Index: [`../README.md`](../README.md). **Product shape:** [`../SHAPE.md`](../SHAPE.md). -**Dialect teach:** openCypher-shaped **GQL** + shaped `pin_map` + gated mutate — [`../grammar/gql-wire-profile.md`](../grammar/gql-wire-profile.md). Product **0.19.3**; **1.0** = 0.5–0.8 claimed (unclaimed; no extra engine). Hatch **0.19.3**; last PyPI **`memnet-llm==0.19.0`** until upload. +**Dialect teach:** openCypher-shaped **GQL** + shaped `pin_map` + gated mutate — [`../grammar/gql-wire-profile.md`](../grammar/gql-wire-profile.md). Product **0.19.5.** Hatch **0.19.5**; published PyPI is **`memnet-llm==0.19.5`**. **1.0** = 0.5–0.8 claimed (unclaimed; no extra engine). Playbook: [`../LLM-GUIDE.md`](../LLM-GUIDE.md). Honesty `c` (`SHAPE_DROP_KEYS`): [`../operations/honesty-c-wire-audit.md`](../operations/honesty-c-wire-audit.md). Changelog: [`../../CHANGELOG.md`](../../CHANGELOG.md) **0.19.5**. **Worked GQL example:** [`examples/inverting-amplifier-gql-case-study.md`](examples/inverting-amplifier-gql-case-study.md). **Decision:** [`../adr/ADR-001-gql-agent-wire.md`](../adr/ADR-001-gql-agent-wire.md). Versions: [`../ROADMAP.md`](../ROADMAP.md). @@ -16,8 +16,9 @@ MemNet is **mission working memory** — named session \(S\), bounded Recall Sha | MUST | MUST NOT | |------|----------| | `session_open` with `SCHEMA` covering every kind you mutate (`map_file` / `map_lines`) | Game `schema.example.txt` unless that *is* the domain | -| Cue then `pin_map(q)`; skip if a *cued* seed is empty; CueConflict when \(|Q|>1\); **drop** prior maps from the prompt; empty \(q\) = outline (not `view=shell`) | Dump \(S\); stuff every map into `messages`; leftover `query_warm` as primary; ANN / `rag_query` of \(S\); Neo4j/Bolt as goldfish; leftover `--anchor` as law | -| Pattern Commit via `mutate` (`CREATE` / `MATCH…SET`); locators as properties | leftover `id:'NEW'` mint; leftover `add`/`update` as TARGET; leftover copy-id `--anchor` as law; silent MERGE-by-name | +| Cue then `pin_map(q)` by labels + observable properties / keyword; skip if a *cued* seed is empty; CueConflict when \(|Q|>1\); **drop** prior maps from the prompt; empty \(q\) = outline (not `view=shell`) | Dump \(S\); stuff every map into `messages`; leftover `query_warm` as primary; ANN / `rag_query` of \(S\); Neo4j/Bolt as goldfish; leftover `--anchor` / leftover copy-id as law | +| Pattern Commit via `mutate` (`CREATE` / `MATCH…SET`); locators as properties; identity is the graph element, not a store key | leftover `id:'NEW'` mint; leftover `add`/`update` as TARGET; leftover copy-id `--anchor` as law; silent MERGE-by-name; treat nickname `id` / `hid` as identity | +| Shaped `pin_map` emit: labels + observable properties only (`SHAPE_DROP_KEYS` drops `hid` / `_memnet_hid` / `elementId`; nickname `id` stays off the wire) | Copy hid / `_memnet_hid` / `elementId` / nickname `id` from emit as identity; leftover `--anchor` as goldfish | | MCP tool arg **`session`** | Tool arg `session_id` (JSON envelope may still *return* `session_id`) | | In-process MCP for a single agent | In-process MCP under Multitask (use TCP / streamable-http) | @@ -25,7 +26,7 @@ Kinds not in the open map fail `unknown_tag`. Bundled maps: `parts/common/memnet | Note | Role | Default map | |------|------|-------------| -| [`examples/inverting-amplifier-gql-case-study.md`](examples/inverting-amplifier-gql-case-study.md) | InvAmp through **GQL-wire** (canonical `CST_*` ground ids) | `SCHEMA CST` + `TSK` in `map_lines` (no bundled circuit map) | +| [`examples/inverting-amplifier-gql-case-study.md`](examples/inverting-amplifier-gql-case-study.md) | InvAmp through **GQL-wire** (canonical `CST_*` ground locators as properties) | `SCHEMA CST` + `TSK` in `map_lines` (no bundled circuit map) | | [`examples/inverting-amplifier-memnet.md`](examples/inverting-amplifier-memnet.md) | InvAmp **math** SSOT (not wire teach) | — | | [`llm-circuit-schematic.md`](domains/llm-circuit-schematic.md) | Schematic / s-domain (GQL) | same as GQL case study | | [`llm-nodal-analysis-formulas.md`](domains/llm-nodal-analysis-formulas.md) | Node method (GQL) | same as GQL case study | diff --git a/docs/application-notes/examples/inverting-amplifier-gql-case-study.md b/docs/application-notes/examples/inverting-amplifier-gql-case-study.md index 7387b89..d4af2b3 100644 --- a/docs/application-notes/examples/inverting-amplifier-gql-case-study.md +++ b/docs/application-notes/examples/inverting-amplifier-gql-case-study.md @@ -31,7 +31,7 @@ MemNet **states** stamps; it does **not** solve the network. | Construct | Convention in this sketch | |-----------|---------------------------| | **Label** | `:CST` (constitutive / device leaf) | -| **Stable id** | property `id` (house pin) | +| **Ground locator** | property `id` (house pin `CST_*`, a locator property — not a store key; nickname `id` stays off shaped `pin_map` emit) | | **Law** | node property `law` (LaTeX string) — **never** on a relationship | | **Ports** | node property `ports` (map / structured bag) — `PortIncidence` | | **Params** | ordinary node properties (`R`, `a_s`, …) | @@ -137,20 +137,20 @@ Agent goldfish read is **not** a raw binding table such as: MATCH (n)-[r]->(m) RETURN n, r, m ``` -Instead, `pin_map(kind='CST', locators=['id=CST_U1'], depth=2, view='shell')` wraps GQL internally and returns a **bounded shaped subgraph** — openCypher-family graph lines the agent can copy when mutating. leftover `pin_map(anchor='CST_U1')` is leftover. `view=shell` here is grain **on that seed**, not session outline (empty q is outline regardless of view): +Instead, `pin_map(kind='CST', locators=['id=CST_U1'], depth=2, view='shell')` wraps GQL internally and returns a **bounded shaped subgraph** — openCypher-family graph lines the agent can reuse as labels+properties when mutating. `locators=['id=CST_U1']` is a **property cue** (ground locator `CST_U1`, not a store key on the wire). leftover `pin_map(anchor='CST_U1')` is leftover. Nickname `id` / `hid` / `_memnet_hid` / `elementId` stay off shaped emit (`SHAPE_DROP_KEYS`). `view=shell` here is grain **on that seed**, not session outline (empty q is outline regardless of view): ```cypher -// shaped emit (illustrative — same family as mutate, ego-bounded) -(:CST {id:'CST_U1', name:'opamp', a_s:1000000, law:'$@ip=0$,$@im=0$,$@vo=a_s*(@vp-@vm)$', ...}) -(:CST {id:'CST_Rin', name:'Rin', R:10000, ...}) -(:CST {id:'CST_Rf', name:'Rf', R:100000, ...}) -(:CST {id:'CST_Gnd', name:'VGND', ...}) -(:CST {id:'CST_A', name:'closed_loop', A_s:-10.0, ...}) -(:CST {id:'CST_U1'})-[:bind {id:'E_sum_r', fromPort:'b', toPort:'inm'}]->(:CST {id:'CST_Rin'}) -(:CST {id:'CST_U1'})-[:bind {id:'E_sum_f', fromPort:'b', toPort:'inm'}]->(:CST {id:'CST_Rf'}) -(:CST {id:'CST_U1'})-[:bind {id:'E_out_f', fromPort:'out', toPort:'a'}]->(:CST {id:'CST_Rf'}) -(:CST {id:'CST_U1'})-[:bind {id:'E_inp', fromPort:'inp', toPort:'a'}]->(:CST {id:'CST_Gnd'}) -(:CST {id:'CST_U1'})-[:bind {id:'E_A_out', fromPort:'out', toPort:'out'}]->(:CST {id:'CST_A'}) +// shaped emit (illustrative — same family as mutate, ego-bounded; nickname id off the wire) +(:CST {name:'opamp', a_s:1000000, law:'$@ip=0$,$@im=0$,$@vo=a_s*(@vp-@vm)$', ...}) +(:CST {name:'Rin', R:10000, ...}) +(:CST {name:'Rf', R:100000, ...}) +(:CST {name:'VGND', ...}) +(:CST {name:'closed_loop', A_s:-10.0, ...}) +(:CST {name:'opamp'})-[:bind {fromPort:'b', toPort:'inm'}]->(:CST {name:'Rin'}) +(:CST {name:'opamp'})-[:bind {fromPort:'b', toPort:'inm'}]->(:CST {name:'Rf'}) +(:CST {name:'opamp'})-[:bind {fromPort:'out', toPort:'a'}]->(:CST {name:'Rf'}) +(:CST {name:'opamp'})-[:bind {fromPort:'inp', toPort:'a'}]->(:CST {name:'VGND'}) +(:CST {name:'opamp'})-[:bind {fromPort:'out', toPort:'out'}]->(:CST {name:'closed_loop'}) ``` Engine-law rows may prepend when present. Recyclable / out-of-budget neighbours stay hidden (MN-REQ-04). @@ -164,7 +164,7 @@ Engine-law rows may prepend when present. Recyclable / out-of-budget neighbours | Device constitutive law | Node property `law` on `:CST` | | Port bags (V/I, direc) | Node property `ports` (`PortIncidence`) | | Copper | Relationship type `:bind` + port endpoint properties | -| Chart / mission links | Other relationship types on bare node ids | +| Chart / mission links | Other relationship types on locators as properties | | Goldfish budget | `PinMapShapedRead` / `pin_map` view+depth+max_rows | | Durable AgensGraph | Optional later; same GQL family — not this sketch | diff --git a/docs/application-notes/system/llm-build-on-memnet.md b/docs/application-notes/system/llm-build-on-memnet.md index e1eb3f0..22207b5 100644 --- a/docs/application-notes/system/llm-build-on-memnet.md +++ b/docs/application-notes/system/llm-build-on-memnet.md @@ -171,7 +171,7 @@ memnet-mcp = "memnet_mcp.server:main" mcp = ["mcp>=1.2,<2"] ``` -Optional-deps keep `pip install memnet-llm` lightweight; only `[mcp]` users pull the `mcp` package. Hatch **0.19.3**; last PyPI **`memnet-llm==0.19.0`** until upload: `pip install 'memnet-llm[mcp]'` (contributors: `pip install -e ".[mcp]"`). +Optional-deps keep `pip install memnet-llm` lightweight; only `[mcp]` users pull the `mcp` package. Hatch **0.19.5**; published PyPI is **`memnet-llm==0.19.5`**: `pip install 'memnet-llm[mcp]'` (contributors: `pip install -e ".[mcp]"`). --- @@ -221,7 +221,7 @@ mcp-memnet/ name: mcp-memnet description: >- Cursor MCP MemNet: token-efficient GQL + shaped pin_map graph - (not JSON) — atomise, pin_map from anchor, goldfish loop via + (not JSON) — atomise, cue then pin_map, goldfish loop via memnet serve or HTTP. Coding, articles, user constraints, SysML/MUD. Triggers: memnet, memnet mcp, pin_map, goldfish loop, atomise, wire format, token efficient, knowledge graph, GQL dialect. @@ -234,8 +234,8 @@ metadata: token_guardrails: | - **Wire format:** GQL + shaped pin_map; short fields, no prose. - **Atomise first:** one fact per row; edges for relations; electrical ports/law/bind. - - **Read:** pin_map with anchor — never bare full-session dump. - - **Write:** add new ids; update changes; copy ids from pin_map. + - **Read:** cue then pin_map — never bare full-session dump; leftover `--anchor` is leftover. + - **Write:** pattern mutate; locators from shaped emit (labels/properties); never treat nickname id / hid as identity. - **Coding:** grep/LSP to verify — then store compact MOD/SYM atoms. - **Session:** pass MCP arg `session` (not `session_id`) on tools. - **Server:** in-process for a single agent; `memnet serve` / HTTP when sharing a graph. diff --git a/docs/application-notes/system/llm-system-dev-multitask.md b/docs/application-notes/system/llm-system-dev-multitask.md index 40364ec..6c61790 100644 --- a/docs/application-notes/system/llm-system-dev-multitask.md +++ b/docs/application-notes/system/llm-system-dev-multitask.md @@ -158,7 +158,7 @@ Client leftover `NEW` mint is leftover, not product. Prefer ingest for bounded p | **leftover `add`** | leftover façade for incremental locators after grep/LSP confirm; prefer `mutate` | | leftover `id:'NEW'` mint | leftover engine; product is GraphElement `CREATE` without NEW | -Re-`pin_map` after ingest/seed; workers copy ids from the slice. +Re-`pin_map` after ingest/seed; workers copy locators / cue from the shaped slice (labels + observable properties), not nickname ids. ---