Skip to content

README.md

Latest commit

 

History

History
140 lines (107 loc) · 14.3 KB

README.md

File metadata and controls

140 lines (107 loc) · 14.3 KB
Raw

MemNet SysML models

Software-only target system model for the MemNet core engine and generic MemNet MCP server.

Layout: sysml-models/ per SYSTEM-REPO-LAYOUT.md and repo LAYOUT.md.

Design authority: rebuilt requirements + ADR-001 (GQL agent wire) + docs/grammar/gql-wire-profile.md. Today's parts/common/memnet and parts/memnet-mcp inform feasibility; see outputs/system-design-notes.md for target vs as-is.

Product framing (2026-08-13)

  1. MemNet = mission working memory — session-scoped NODE|EDGE buffer (brand SharedLlmMemory); not the search corpus, not GraphRAG. In-session recall = serial cue then pin_map; host RAG may propose locators only.
  2. Session as SSOT handle — pass a mission SOMETHING by session id only (SessionHandoff / SessionHandoffById); module A→B pipe; peers re-pin_map; chat / MissionDock / HTTP never carry the graph. sessionId = secret capability (MUST NOT dump in chat/queue).
  3. Durable online GQL store behind MemNet (DurableBuffer / AgensGraphAdapter) — M2.5 / 0.7 claim is adapter + operator round trip (no runtime caller). Neo4j cabinet is on the archive shelf (#187). Cabinet external / not vendored. LLM↔store direct (Bolt) out of teach.
  4. Lead imports member working memory — happy path A shared session → re-pin_map (no second store; no ImportGuard). Path B → WorkingMemorySlice through optional nested ImportGuard (ImportGuardHook shipped; CheapLlmImportGuard shipped #63) then ImportAbsorb (engine hard). Product verb = import. Colloquial "session merge" means this import only (no SessionMerge* types). Distinct from Cypher MERGE and micro id re-id merge=true.
  5. CapsPolicy ACL cut — as-is shipped when session ACL is enabled: who, pin_map-vs-mutate, WorkerWriteScope hard reject, and optional SessionBind. engineAclShipped=true; ACL remains off by default.

Sequence: M1 (done) → M2 (done) → M2.5 (0.7 adapter + operator round trip, no runtime caller) → M3 (0.8 in-repo playbook/app-note GQL rewrite, done). 1.0 = claim of 0.5–0.8. Design: Snap this product model (ProjectMemNet) into multiple sessions (catalog + package interiors); goldfish one interior. Not one ingest of the tree, not one session per file. docs/extras/memnet-session-strata.md.

Packages

File Package Role
models/connections.sysml MemNetConnections SharedLlmMemory, SessionHandoff (+ CallerId / SessionBind / SessionCapability), WorkingMemorySlice, SessionImportRequest, optional ImportGuardDecision; ServeUsageLook / ImportGuardArmedLook / HumanUsagePage (ops look); application CompanyAnalyticalSsot / HostSearchBridge / DeviceMemNetFleet / TipMemNetAccess / MemNetLanMcpCluster / MemNetTwoMovesContrast
models/requirements.sysml MemNetRequirements MN-REQ-00…13 (01.7/01.8, 06.4, 06.5 human usage look, 06.6 device services / one droplet MemNet MCP tip/ops, product face sysmledge, 06.7 SSOT → code allocate, 06.8 tip MemNet access portal, 06.9 ClusterRoute LAN MCP front invent #191, 06.10 SliceHandCarry invent #47 cousin, 06.12 product gateway on memnet-mcp, 12.9–12.13, 13.1 Recall/Commit; 02.9 cousin store-key; 04.8 cue |Q|>1; 04.9 empty-q outline)
models/cousins.sysml MemNetCousinContrast TARGET vs eight cousin pointing/identity designs (not a product switch; SysMLEdge is a distinct pin_map; overlay family SysMLEdgePrj-*; this engine repo and modelbasedPrj-* are repo-based — MUST NOT use SysMLEdge as model SSOT; SysMLEdgePrj-* bound desk is working model SSOT)
models/deploy.sysml MemNet Nested parts; RecallCommit two-operator cut; Multitask spine; MemNetUsageDashboard / MemNetOpsFleet / TipMemNetAccessPortal / MemNetLanMcpFront / MemNetProductGateway / MemNetTwoMoves outside MemNetSystem
models/implementation.sysml MemNetImplementation SoftwareAllocate logical → live modules; one Hatch wheel many hosts; sysmledge not in wheel
models/behaviour.sysml MemNetBehaviour HandoffById, SessionImportReceive, Multitask async, landed-client hydrate/flush
models/verify.sysml MemNetVerification MN-VER-12-G00 + S01…S14; MN-VER-04-S01…S05; MN-VER-09-S01; MN-VER-13-S01; MN-VER-06-S01…S10 (S06 storage roles; S07 ClusterRoute LAN MCP front; S08 two named moves; S09 admin usage; S10 product gateway); MN-VER-01-S03
models/root.sysml ProjectMemNet Root imports (load last). MUST NOT import MemNetArchive
models/archive.sysml MemNetArchive ARCHIVE shelf (leftover_* / TierACodec / LegacyPipe* / retired Neo4j). Off config.yaml load

One-page nest: outputs/product-nest-one-page.md.

Nesting outline (target)

MemNetSystem                                 // SharedLlmMemory product
├── Core
│   ├── Session                              // session id = SSOT handle
│   ├── GQL                                  // GqlCodec + ProductGqlGate
│   └── RecallCommit                         // TWO operators
│       ├── Recall                           // cue → pin_map
│       └── Commit                           // mutate
├── Multitask
│   ├── Path A                               // shared session → re-pin
│   └── Path B                               // ImportGuard optional → ImportAbsorb
└── DurableBuffer                            // one primary cabinet story

APPLICATION LOOK   CousinPointingContrast / HostSearchBridge (outside)
ARCHIVE LOOK       MemNetArchive — leftover fog + retired Neo4j (#187); root does not import
OPS LOOK           MemNetUsageDashboard — look only; not agent wire
OPS FLEET          MemNetOpsFleet — device MemNet services; one MemNet MCP at droplet (tip/ops; tip≠face)
OPS ACCESS         TipMemNetAccessPortal — invite + Google login + Bearer for keyed tip MCP (tip≠face; not sysmledge; portal sidecar)
OPS LAN FRONT      MemNetLanMcpFront — ClusterRoute: one MCP catalogue over N LAN serves (inventOnly #191; tip≠face; not shipped)
OPS TWO MOVES      MemNetTwoMoves — ClusterRoute vs SliceHandCarry (inventOnly #191 / #47 cousin; explicit copy ≠ live hop; not shipped)
IMPLEMENTATION     MemNetImplementation — SoftwareAllocate SSOT → live modules; tracker ledger; one wheel many hosts

Happy path Multitask: Path A shared session → re-pin_map (ImportGuard unused). Path B uses optional ImportGuard nest then ImportAbsorb. Hook shipped ≠ cheap LLM shipped.

Story: SessionHandoffById → AsyncTaskDispatch (end turn) → workers async → host EvWorkerReturn → (happy path A: shared re-pin_map | path B: SessionImportReceive → optional Guard → Absorb → Settle).

Target subsystems

  • AgentMemory (SharedLlmMemory): GraphStore, GqlCodec, RecallCommit (Recall: SessionOutline empty-q census + AgentShapedRead / PinMapShapedRead + BoundedMatchFind; Commit: MutateGate + RSV lease), SessionLifecycle
  • MCP / CLI: LLM ↔ MemNet only (not DurableBuffer as primary)
  • DurableBuffer: AgensGraphAdapter client; 0.7 claim is adapter + operator round trip (no runtime caller); Neo4j retired to archive (#187); cabinet external / not vendored
  • Multitask: nested lead handoff + AsyncTaskDispatch + WorkerPool + import spine; MN-REQ-12
  • Path-B PinMapIngest: all domains shipped (memnet.pin_map_ingest; CLI/MCP ingest sysml|codebase|pcba|skills). CatalogSnap 0.15: memnet snap model / MCP snap_model + session_list (sessions|n/max) + session_close. PinMapExport 0.19: cue pin_map GQL write-out (memnet export pin-map). Re-ingest / .sysml reverse (#66) not claimed.
  • Optional soft policy: ImportGuard nest (path B): ImportGuardHook shipped; CheapLlmImportGuard shipped (#63; env-gated); happy path A = re-pin without guard
  • WorkerWriteScope: CapsPolicy / MutateGate hard-rejects out-of-scope mutate when session ACL is enabled; overlap: serialise or RSV lease
  • CapsPolicy ACL (as-is): who / pin_map-vs-mutate / WorkerWriteScope hard reject / optional bind are shipped (engineAclShipped=true); MutateGate, PinMapShapedRead, and SessionHandoffEmit consult; ACL is off by default
  • Out of scope: novel-writer; EvidenceCentre / MissionDock / CompanyMemory / HostSearchBridge / CousinPointingContrast / MemNetUsageDashboard / MemNetOpsFleet / TipMemNetAccessPortal / MemNetLanMcpFront / MemNetTwoMoves MUST NOT nest under MemNetSystem (optional host locators 0.17 / cousin pointing contrast / human usage look / device fleet with one droplet MemNet MCP tip/ops; product face is sysmledge / tip access portal is ops key gating, not that product / LAN MCP front is invent-only #191 / SliceHandCarry is invent-only #47 cousin)
  • ARCHIVE (off ProjectMemNet load): leftover_* / TierACodec / LegacyPipe* / retired Neo4j cabinet in models/archive.sysml (MemNetArchive). Root MUST NOT import it. Engine leftover codecs may remain on disk for tests; the Neo4j adapter module is removed. Product teach is GQL only.

CapsPolicy ACL (as-is 0.8)

Check As-is
Who (CallerId) Shipped when session ACL is enabled
pin_map (read) vs mutate Distinct shipped permissions
WorkerWriteScope HARD reject on out-of-scope mutate
Optional SessionBind Shipped; missionId + lease match, with documented in-process skip-bind

Neighbourhood reserve (RSV) and all Path-B PinMapIngest_* domains are shipped; full private/shared/open session_token modes remain deferred. sessionId is a secret capability and MUST NOT be dumped. No Dock nest is introduced.

Case studies

Two shelves (detail + principles: outputs/README.md). Product canon = MemNet mechanism. Application examples = patterns on SharedLlmMemory — not extra product cores.

Product canon

Study Path
Goldfish chat desync → re-pin outputs/goldfish-chat-desync-case-study.md
Multitask Mode (GQL pins + optional import) outputs/multitask-case-study.md
Async parallel (canon companion) outputs/async-parallel-conflict-case-study.md
TCP / streamable-http shared Multitask (transport) outputs/tcp-shared-multitask-case-study.md
Session import + optional ImportGuard (path B) outputs/session-import-case-study.md
Snapshot passport outputs/snapshot-passport-case-study.md
Empty-cue session outline outputs/session-outline-case-study.md
Human usage look (read-only dashboard; HTTP parked) outputs/usage-dashboard-case-study.md
Device fleet (one MemNet MCP at droplet, tip≠face; not #47) outputs/device-fleet-one-mcp-case-study.md
Tip MemNet access portal (keyed Bearer; portal sidecar) outputs/tip-memnet-access-portal-case-study.md
LAN MCP front (ClusterRoute; one catalogue, N LAN serves; inventOnly #191) outputs/lan-mcp-front-case-study.md
Product gateway (memnet-mcp route to one owning serve; MN-REQ-06.12) outputs/product-gateway-case-study.md
ClusterRoute vs SliceHandCarry (two named moves; inventOnly #191 / #47 cousin) outputs/cluster-route-vs-slice-hand-carry-case-study.md
SSOT → code allocate (one Hatch wheel, many hosts) outputs/ssot-to-code-allocate-case-study.md
SSOT → code tracker map outputs/ssot-to-code-allocate-map.md
Durable hydrate/flush (M2.5) outputs/durable-hydrate-flush-case-study.md

Application examples (on SharedLlmMemory)

Study Path
Company analytical SSOT (COM_*) outputs/company-memory-case-study.md
Evidence Centre (ai-investor librarian / MissionDock) outputs/evidence-centre-case-study.md
Host search nest (RAG / index outside MemNetSystem) outputs/host-search-nest-case-study.md
Inverting amp bind vs relation (ego CST_U1) outputs/inverting-amp-bind-relation-case-study.md
Tech docs / SCPI atomisation outputs/tech-docs-scpi-case-study.md
SysML modelling goldfish (MBSE meta) outputs/sysml-modeling-goldfish-case-study.md

Live pin map (MN-REQ-04)

Turn-facing agent payload = shaped subgraph via PinMapShapedRead (pin_map from a cue) when the seed is non-empty. leftover --anchor is leftover. A dark session with empty q is outline (Recall census of S: kinds + LIMIT exemplars) — not a neighbourhood, not leftover skip, not view=shell, not Peak_L. A non-empty codebook miss last-resorts Peak_L ((\rho^*) residual local max) then ShapeWalk — never default goldfish. Sibling BoundedMatchFind (MN-REQ-04.6) is shipped as seed-only query find / MCP find (implemented=true; #73) — not a k-hop walk; do not teach MATCH…RETURN as goldfish. When (|Q|>1), CueConflict. MATCH_L, Peak_L, outline, and ShapeWalk are one Recall operator (docs/grammar/math-skeleton.md).

Property-graph ontology (first-class)

Node / Edge / Property / Label — docs/grammar/gql-wire-profile.md. Agent wire = GQL only. Parse front: GraphGlot; product gate after parse. Grammar spelling SSOT: vendored docs/grammar/openCypher.bnf.

Validate

Prefer Cursor SysML v2 MCP validate on files under models/. Load order: config.yaml.

Anchor

TSK_model_memnet — see AGENT-CONTEXT.md.