memnet-llm 0.3.2

In-memory working-memory graph CLI for LLM agents (goldfish brain scratch space)

MemNet

MemNet (Net of Memory) is an in-memory NODE | EDGE graph that sits between pipelines of LLM calls and data search. It is working memory for agents — not a chat notepad and not the search corpus.

Aims (MN-REQ-00): save wall-clock time and tokens while keeping factual accuracy when presenting facts. It aids system, programme, software, firmware, hardware, and documentation development.

Version: see project.toml / package memnet-llm (CLI command remains memnet). Python ≥ 3.11.

---

Doctrine (target)

Idea	Meaning
NODE | EDGE only	Conceptual kinds are nodes and edges; tags realise node kinds
One agent dialect	Shared dialect (Write = display) — same shapes for live read and mutate; design docs may still say “Tier A”
Live pin map	Bounded ego/anchor digest for the turn (not a session dump)
NEW vs locators	LLM creates use mint token NEW; pin-map ingest uses stable locators (no client NEW for source pins). PCBA schematics use Atopile .ato
Transport	In-process first; local IPC next; TCP localhost as migration fallback
Persistence	Optional snapshots (session save / session load); sessions are RAM + TTL

Primary term: pin map. MCP tool pin_map / CLI query pin-map. Legacy aliases: query_warm / query warm.

---

Agent I/O (shared dialect)

Target surface (not @TAG pipe). Shared NODE | EDGE field shapes (Write = display). Mutate uses ops (+ create, ~ update, - drop). Live pin map emits bare present lines — no leading ops (ops are mutate-only; a pin-map + would look like “please add”).

Mutate input (LLM → MemNet) — may use [NEW]; engine mints ids:

## Nodes
+ CLM [NEW] ; type=decision ; code=bitrate cap 2000 bps ; recycle=persistent
+ TSK [T42] ; goal=Clear warehouse ; status=in_progress ; recycle=persistent

## Edges
+ E77 [N03] --(helps)--> [T42] ; note=labour ; recycle=persistent

Live pin map output (MemNet → LLM) — assigned ids, no NEW; copyable for the next mutate:

## Nodes
CLM [C12] ; type=decision ; code=bitrate cap 2000 bps ; recycle=persistent
TSK [T42] ; goal=Clear warehouse ; phase=2 ; status=in_progress ; recycle=persistent
NPC [N03] ; role=helper ; status=active ; recycle=persistent

## Edges
E77 [N03] --(helps)--> [T42] ; note=labour ; recycle=persistent

• Create: [NEW] / leading NEW — engine allocates ids; copy them afterwards.
• Update / settle: known ids only; NEW illegal on patch.
• Pin-map ingest (SysML, codebase, PCBA .ato, skills): deterministic ids from locators (refdes=, path=, qname=, …); reject client NEW for those pins.

Design and examples: docs/grammar/memnet-grammar-design.md, docs/grammar/examples/. SysML notes: sysml-models/outputs/system-design-notes.md.

---

Current vs target (honest)

Area	Today (as-is)	Target
Agent wire	Mutate + live pin map prefer shared dialect; legacy @TAG pipe still accepted on add/update and used in snapshots / read	Shared shapes; pin map bare present; mutate keeps ops
Shared-dialect codec	Pure-Python codec in memnet/tier_a.py + golden tests	SSOT parse/emit; ANTLR optional later
Id mint	IdAllocator wired through MutateGate on shared-dialect batches	Same
MutateGate	mutate_gate.py — shared-dialect parse → mint → commit; pipe import-once	Same dialect only
Live pin map	PinMapComposer via pin_map / query pin-map (shared-dialect emit)	Done
Transport	MCP in-process by default; MEMNET_MCP_TRANSPORT=tcp for serve	In-process primary; local IPC; TCP fallback
MCP	Generic tools; in-process engine	Same
Novel-writer	Removed — see DROP-NOVEL-WRITER.md	Stay out of this repo

docs/LLM-GUIDE.md is still largely pipe-centric (goldfish loop, query warm). Prefer the grammar design + SysML notes for the forward dialect; treat the GUIDE as operational until it is migrated.

---

Layout

Part-based tree (LAYOUT.md, AGENTS.md):

Path	Role
parts/common/memnet/	Core library + CLI (memnet)
parts/memnet-mcp/	Generic MCP server (memnet-mcp)
docs/	LLM-GUIDE, grammar, application notes
sysml-models/	Requirements and deploy/behaviour models
tests/	Engine, MCP, shared-dialect golden tests

Do not recreate top-level src/ or applications/. Do not restore parts/novel-writer/.

---

Installation

pip install memnet-llm
# or from source:
pip install -e ".[dev]"
# optional MCP:
pip install memnet-llm[mcp]

PyPI name is memnet-llm (memnet on PyPI is a different project).

---

Quick start (as-is CLI)

Until the shared dialect is universal at every boundary, CLI sessions still use serve; agent mutate prefers the shared dialect.

Terminal 1:

memnet serve
# MEMNET_SERVE=127.0.0.1:18765

Terminal 2:

memnet session open --map-file parts/common/memnet/memnet/examples/schema.example.txt
$env:MEMNET_SESSION = "mn_xxxxxxxx"   # from stderr

memnet add --file parts/common/memnet/memnet/examples/workflow.example.txt
memnet query pin-map --anchor PLR01   # live pin map (bare present; query warm is legacy)

memnet session close $env:MEMNET_SESSION

Without memnet serve, stateful commands fail with @ERR: serve_required (unless MEMNET_TEST_INLINE=1 for tests/scripts).

MCP (as-is): run memnet serve, then memnet-mcp. Tools include serve_status, session_open, session_current, session_load, session_save, pin_map (query_warm alias), query_walk, add, update, read_get, housekeep_stats. Envelope is JSON; memory payload is still pipe lines today.

Forward reading order for agents:

1. docs/grammar/memnet-grammar-design.md — shared dialect (Write = display), pin map, NEW vs locators
2. sysml-models/outputs/system-design-notes.md — target part tree and gaps
3. docs/LLM-GUIDE.md — current goldfish loop (pipe; migration pending)

---

What was removed

Novel-writer (parts/novel-writer/, novel MCP extras, novel application notes) is out of scope. This repository hosts the graph engine and generic memnet-mcp only. Record: DROP-NOVEL-WRITER.md.

---

Licence

MIT