network-ai 4.4.2 → 4.5.0

package/INTEGRATION_GUIDE.md

@@ -115,6 +115,7 @@ Match your problem to the Network-AI primitive:
 | Race conditions in parallel agent writes | `LockedBlackboard` with `priority-wins` | Higher-priority agents preempt lower-priority writes on conflict |
 | Need to expose all tools to an AI via MCP | `McpSseServer` + `network-ai-server` | HTTP/SSE server at `GET /sse`, `POST /mcp`, `GET /tools` |
 | Runtime AI control of the orchestrator | `ControlMcpTools` | AI can read/set config, spawn/stop agents, drive FSM transitions |
+| Agents lose project context between sessions | `ProjectContextManager` (`context_manager.py`) | Persistent Layer-3 JSON file injected into every agent's system prompt |
 
 ---
 

package/QUICKSTART.md

@@ -445,6 +445,67 @@ python scripts/revoke_token.py --cleanup
 python scripts/validate_token.py --token "grant_85364b44..."
 ```
 
+### Project Context (Layer 3 — Persistent Memory)
+
+Long-lived project state that every agent inherits, regardless of session:
+
+```bash
+# Initialise once
+python scripts/context_manager.py init \
+  --name "MyProject" \
+  --description "Multi-agent workflow" \
+  --version "1.0.0"
+
+# Print formatted block to inject into agent system prompts
+python scripts/context_manager.py inject
+
+# Record an architecture decision
+python scripts/context_manager.py update \
+  --section decisions \
+  --add '{"decision": "Use atomic blackboard commits", "rationale": "Prevent race conditions"}'
+
+# Update milestones
+python scripts/context_manager.py update --section milestones --complete "Ship v1.0"
+python scripts/context_manager.py update --section milestones --add '{"planned": "Vector memory integration"}'
+
+# Set tech stack
+python scripts/context_manager.py update --section stack --set '{"language": "TypeScript", "runtime": "Node.js 18"}'
+
+# Add a goal or ban an approach
+python scripts/context_manager.py update --section goals --add "Ship v2.0 before Q3"
+python scripts/context_manager.py update --section banned --add "Direct DB writes from agents"
+
+# Print full context as JSON
+python scripts/context_manager.py show
+```
+
+Context is stored in `data/project-context.json`. The `inject` command outputs a markdown block ready to prepend to any agent's system prompt.
+
+---
+
+## Use with Claude, ChatGPT & Codex
+
+Three integration files are included in the repo root:
+
+| File | Use |
+|---|---|
+| [`claude-tools.json`](claude-tools.json) | Claude API tool use & OpenAI Codex — drop into the `tools` array |
+| [`openapi.yaml`](openapi.yaml) | Custom GPT Actions — import directly in the GPT editor |
+| [`claude-project-prompt.md`](claude-project-prompt.md) | Claude Projects — paste into Custom Instructions |
+
+**Claude API / Codex:**
+```js
+import tools from './claude-tools.json' assert { type: 'json' };
+// Pass tools array to anthropic.messages.create({ tools }) or OpenAI chat completions
+```
+
+**Custom GPT Actions:**
+In the GPT editor → Actions → Import from URL, or paste `openapi.yaml` directly.
+Set the server URL to your running `npx network-ai-server --port 3001` instance.
+
+**Claude Projects:**
+Copy the contents of `claude-project-prompt.md` into a Claude Project's Custom Instructions field. No server required for instruction-only mode.
+
 ---
 
 ## Fan-Out / Fan-In Pattern

package/SKILL.md

@@ -33,6 +33,24 @@ metadata:
 
 > **Scope of this skill bundle:** All instructions below run local Python scripts (`scripts/*.py`). No network calls are made by this skill. Tokens are UUID-based (`grant_{uuid4().hex}`) stored in `data/active_grants.json`. Audit logging is plain JSONL (`data/audit_log.jsonl`) — no HMAC signing in the Python layer. HMAC-signed tokens, AES-256 encryption, and the standalone MCP server are all features of the **companion Node.js package** (`npm install -g network-ai`) — they are **not** implemented in these Python scripts and do **not** run automatically.
 
+## Setup
+
+**No pip install required.** All 5 scripts use Python standard library only — zero third-party packages.
+
+```bash
+# Prerequisite: python3 (any version ≥ 3.8)
+python3 --version
+
+# That's it. Run any script directly:
+python3 scripts/blackboard.py list
+python3 scripts/swarm_guard.py budget-init --task-id "task_001" --budget 10000
+
+# Optional: for cross-platform file locking on Windows production hosts
+pip install filelock  # only needed if you see locking issues on Windows
+```
+
+The `data/` directory is created automatically on first run. No configuration files, environment variables, or credentials are required.
+
 Multi-agent coordination system for complex workflows requiring task delegation, parallel execution, and permission-controlled access to sensitive APIs.
 
 ## 🎯 Orchestrator System Instructions
@@ -147,6 +165,85 @@ python {baseDir}/scripts/blackboard.py write "task:001:final" \
 
 ---
 
+## The 3-Layer Memory Model
+
+Every agent in the swarm operates with three memory layers, each with a different scope and lifetime:
+
+| Layer | Name | Lifetime | Managed by |
+|-------|------|----------|------------|
+| **1** | Agent context | Ephemeral — current task only | Platform (per-session) |
+| **2** | Blackboard | TTL-scoped — shared across agents | `scripts/blackboard.py` |
+| **3** | Project context | Persistent — survives all sessions | `scripts/context_manager.py` |
+
+### Layer 1 — Agent Context
+Each agent's own context window: the current task instructions, conversation history, and immediate working memory. Managed automatically by the OpenClaw/LLM platform. Nothing to configure.
+
+### Layer 2 — Blackboard (Shared Coordination State)
+A shared markdown file (`swarm-blackboard.md`) for real-time cross-agent coordination: task results, grant tokens, status flags, and TTL-scoped cache entries. Agents read and write via `scripts/blackboard.py`. Entries expire automatically.
+
+### Layer 3 — Project Context (Persistent Long-Term Memory)
+A JSON file (`data/project-context.json`) that holds information every agent should know, regardless of what session or task is running:
+- **Goals** — long-term objectives of the project
+- **Tech stack** — languages, frameworks, infrastructure
+- **Milestones** — completed, in-progress, and planned work
+- **Architecture decisions** — design choices and their rationales
+- **Banned approaches** — approaches that have been ruled out
+
+#### Initialising Project Context
+
+```bash
+python {baseDir}/scripts/context_manager.py init \
+  --name "MyProject" \
+  --description "Multi-agent workflow automation" \
+  --version "1.0.0"
+```
+
+#### Injecting Context into an Agent System Prompt
+
+```bash
+python {baseDir}/scripts/context_manager.py inject
+```
+
+Copy the output block to the top of your agent's system prompt. Every agent that receives this block shares the same long-term project awareness.
+
+#### Recording a Decision
+
+```bash
+python {baseDir}/scripts/context_manager.py update \
+  --section decisions \
+  --add '{"decision": "Use atomic blackboard commits", "rationale": "Prevent race conditions in parallel agents"}'
+```
+
+#### Updating Milestones
+
+```bash
+# Mark a milestone complete
+python {baseDir}/scripts/context_manager.py update \
+  --section milestones --complete "Ship v2.0"
+
+# Add a planned milestone
+python {baseDir}/scripts/context_manager.py update \
+  --section milestones --add '{"planned": "Integrate vector memory"}'
+```
+
+#### Setting the Tech Stack
+
+```bash
+python {baseDir}/scripts/context_manager.py update \
+  --section stack \
+  --set '{"language": "TypeScript", "runtime": "Node.js 18", "framework": "Network-AI v4.5"}'
+```
+
+#### Banning an Approach
+
+```bash
+python {baseDir}/scripts/context_manager.py update \
+  --section banned \
+  --add "Direct database writes from agent scripts (use permission gating)"
+```
+
+---
+
 ## When to Use This Skill
 
 - **Task Delegation**: Route work to specialized agents (data_analyst, strategy_advisor, risk_assessor)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "network-ai",
-  "version": "4.4.2",
+  "version": "4.5.0",
   "description": "AI agent orchestration framework for TypeScript/Node.js - 14 adapters (LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw, A2A, Codex + streaming variants). Built-in CLI, security, swarm intelligence, real-time streaming, and agentic workflow patterns.",
   "homepage": "https://github.com/jovanSAPFIONEER/Network-AI#readme",
   "main": "dist/index.js",

package/scripts/context_manager.py

@@ -0,0 +1,334 @@
+#!/usr/bin/env python3
+# SECURITY: This script makes NO network calls and spawns NO subprocesses.
+# All I/O is local file operations only:
+#   READS:  data/project-context.json, data/audit_log.jsonl
+#   WRITES: data/project-context.json, data/audit_log.jsonl
+# Imports used: argparse, json, sys, datetime, pathlib, typing
+# No imports of: requests, socket, subprocess, urllib, http, ssl, ftplib, smtplib
+"""
+Project Context Manager - Persistent Layer-3 Memory for Agent Swarms
+
+Maintains a JSON file that stores long-lived project context: goals, architecture
+decisions, tech stack, milestones, and banned approaches. This context is injected
+into every agent session so all agents share the same project-level awareness,
+regardless of what's currently on the short-term blackboard.
+
+THE 3-LAYER MEMORY MODEL
+  Layer 1 — Agent context    : current task, immediate instructions (ephemeral, per-agent)
+  Layer 2 — Blackboard       : task results, grants, coordination state (shared, TTL-scoped)
+  Layer 3 — Project context  : architecture decisions, goals, stack, milestones (THIS FILE)
+
+Usage:
+    python context_manager.py init --name "MyProject" [--description "..."] [--version "1.0.0"]
+    python context_manager.py show
+    python context_manager.py inject
+    python context_manager.py update --section decisions  --add '{"decision": "...", "rationale": "..."}'
+    python context_manager.py update --section milestones --complete "task name"
+    python context_manager.py update --section milestones --add '{"planned": "task name"}'
+    python context_manager.py update --section stack     --set '{"language": "TypeScript"}'
+    python context_manager.py update --section goals     --add "Ship v2.0 before Q3"
+    python context_manager.py update --section banned    --add "Direct DB writes from agents"
+
+Examples:
+    python context_manager.py init --name "Network-AI" --description "Multi-agent swarm framework" --version "4.5.0"
+    python context_manager.py update --section decisions --add '{"decision": "Use atomic blackboard commits", "rationale": "Prevent race conditions"}'
+    python context_manager.py update --section milestones --complete "v4.4.3 ClawHub clean-scan"
+    python context_manager.py inject
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, cast
+
+CONTEXT_PATH = Path(__file__).parent.parent / "data" / "project-context.json"
+AUDIT_LOG_PATH = Path(__file__).parent.parent / "data" / "audit_log.jsonl"
+
+EMPTY_CONTEXT: dict[str, Any] = {
+    "project": {
+        "name": "",
+        "description": "",
+        "version": ""
+    },
+    "goals": [],
+    "stack": {},
+    "milestones": {
+        "completed": [],
+        "in_progress": [],
+        "planned": []
+    },
+    "decisions": [],
+    "banned_approaches": [],
+    "agents": {},
+    "updated_at": ""
+}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _load() -> dict[str, Any]:
+    if not CONTEXT_PATH.exists():
+        print(
+            f"[context_manager] No project context found at {CONTEXT_PATH}.\n"
+            "Run: python context_manager.py init --name \"YourProject\"",
+            file=sys.stderr
+        )
+        sys.exit(1)
+    with CONTEXT_PATH.open("r", encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def _save(ctx: dict[str, Any]) -> None:
+    ctx["updated_at"] = _now_iso()
+    CONTEXT_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with CONTEXT_PATH.open("w", encoding="utf-8") as fh:
+        json.dump(ctx, fh, indent=2)
+        fh.write("\n")
+
+
+def _audit(action: str, detail: dict[str, Any]) -> None:
+    entry: dict[str, Any] = {
+        "timestamp": _now_iso(),
+        "action": action,
+        "details": {"source": "context_manager", **detail}
+    }
+    AUDIT_LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with AUDIT_LOG_PATH.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(entry) + "\n")
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+def cmd_init(args: argparse.Namespace) -> int:
+    if CONTEXT_PATH.exists():
+        print(f"[context_manager] Context file already exists at {CONTEXT_PATH}.")
+        print("Use 'update' to change individual sections, or delete the file to reinitialise.")
+        return 1
+
+    ctx = json.loads(json.dumps(EMPTY_CONTEXT))  # deep copy
+    ctx["project"]["name"] = args.name
+    ctx["project"]["description"] = args.description or ""
+    ctx["project"]["version"] = args.version or ""
+    _save(ctx)
+    _audit("init", {"name": args.name, "version": args.version})
+    print(f"[context_manager] Project context initialised: {CONTEXT_PATH}")
+    return 0
+
+
+def cmd_show(args: argparse.Namespace) -> int:  # noqa: ARG001
+    ctx = _load()
+    print(json.dumps(ctx, indent=2))
+    return 0
+
+
+def cmd_inject(args: argparse.Namespace) -> int:  # noqa: ARG001
+    """Print a formatted block suitable for injection into an agent system prompt."""
+    ctx = _load()
+    p = ctx.get("project", {})
+
+    lines: list[str] = []
+    lines.append("## Project Context (Layer 3 — Persistent Memory)")
+    lines.append("")
+
+    if p.get("name"):
+        name_str = p["name"]
+        if p.get("version"):
+            name_str += f" v{p['version']}"
+        lines.append(f"**Project:** {name_str}")
+    if p.get("description"):
+        lines.append(f"**Description:** {p['description']}")
+    lines.append("")
+
+    goals = ctx.get("goals", [])
+    if goals:
+        lines.append("### Goals")
+        for g in goals:
+            lines.append(f"- {g}")
+        lines.append("")
+
+    stack = ctx.get("stack", {})
+    if stack:
+        lines.append("### Tech Stack")
+        for k, v in stack.items():
+            lines.append(f"- **{k}**: {v}")
+        lines.append("")
+
+    milestones = ctx.get("milestones", {})
+    in_progress = milestones.get("in_progress", [])
+    planned = milestones.get("planned", [])
+    completed = milestones.get("completed", [])
+    if in_progress or planned or completed:
+        lines.append("### Milestones")
+        for item in in_progress:
+            lines.append(f"- 🔄 {item} *(in progress)*")
+        for item in planned:
+            lines.append(f"- ⏳ {item}")
+        for item in completed:
+            lines.append(f"- ✅ {item}")
+        lines.append("")
+
+    decisions = ctx.get("decisions", [])
+    if decisions:
+        lines.append("### Architecture Decisions")
+        for d in decisions:
+            if isinstance(d, dict):
+                d_typed: dict[str, Any] = cast(dict[str, Any], d)
+                dec: str = str(d_typed.get("decision", d))
+                rat: str = str(d_typed.get("rationale", ""))
+                lines.append(f"- **{dec}**" + (f" — {rat}" if rat else ""))
+            else:
+                lines.append(f"- {d}")
+        lines.append("")
+
+    banned = ctx.get("banned_approaches", [])
+    if banned:
+        lines.append("### Banned Approaches")
+        for b in banned:
+            lines.append(f"- ❌ {b}")
+        lines.append("")
+
+    lines.append(f"*Context last updated: {ctx.get('updated_at', 'unknown')}*")
+
+    print("\n".join(lines))
+    return 0
+
+
+def cmd_update(args: argparse.Namespace) -> int:
+    ctx = _load()
+    section = args.section
+
+    if section == "decisions":
+        if not args.add:
+            print("[context_manager] --add is required for section 'decisions'", file=sys.stderr)
+            return 1
+        entry: Any = json.loads(args.add)
+        ctx.setdefault("decisions", []).append(entry)
+        _audit("update_decisions", {"added": entry})
+
+    elif section == "milestones":
+        milestones = ctx.setdefault("milestones", {"completed": [], "in_progress": [], "planned": []})
+        if args.complete:
+            name = args.complete
+            # Move from in_progress or planned → completed
+            for bucket in ("in_progress", "planned"):
+                lst: list[Any] = milestones.setdefault(bucket, [])
+                if name in lst:
+                    lst.remove(name)
+            milestones.setdefault("completed", []).append(name)
+            _audit("milestone_complete", {"name": name})
+        elif args.add:
+            entry: Any = json.loads(args.add)
+            if isinstance(entry, dict):
+                for bucket in ("planned", "in_progress", "completed"):
+                    if bucket in entry:
+                        milestones.setdefault(bucket, []).append(entry[bucket])
+                        _audit("milestone_add", {"bucket": bucket, "name": entry[bucket]})
+            else:
+                milestones.setdefault("planned", []).append(str(entry))
+                _audit("milestone_add", {"bucket": "planned", "name": str(entry)})
+        else:
+            print("[context_manager] Provide --add or --complete for section 'milestones'", file=sys.stderr)
+            return 1
+
+    elif section == "stack":
+        if not args.set:
+            print("[context_manager] --set is required for section 'stack'", file=sys.stderr)
+            return 1
+        updates = json.loads(args.set)
+        ctx.setdefault("stack", {}).update(updates)
+        _audit("update_stack", {"updates": updates})
+
+    elif section == "goals":
+        if not args.add:
+            print("[context_manager] --add is required for section 'goals'", file=sys.stderr)
+            return 1
+        ctx.setdefault("goals", []).append(args.add)
+        _audit("update_goals", {"added": args.add})
+
+    elif section == "banned":
+        if not args.add:
+            print("[context_manager] --add is required for section 'banned'", file=sys.stderr)
+            return 1
+        ctx.setdefault("banned_approaches", []).append(args.add)
+        _audit("update_banned", {"added": args.add})
+
+    elif section == "project":
+        if not args.set:
+            print("[context_manager] --set is required for section 'project'", file=sys.stderr)
+            return 1
+        updates = json.loads(args.set)
+        ctx.setdefault("project", {}).update(updates)
+        _audit("update_project", {"updates": updates})
+
+    else:
+        print(f"[context_manager] Unknown section '{section}'. "
+              "Valid: decisions, milestones, stack, goals, banned, project", file=sys.stderr)
+        return 1
+
+    _save(ctx)
+    print(f"[context_manager] Section '{section}' updated.")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="context_manager.py",
+        description="Project Context Manager — Layer-3 persistent memory for agent swarms"
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # init
+    p_init = sub.add_parser("init", help="Initialise a new project context file")
+    p_init.add_argument("--name", required=True, help="Project name")
+    p_init.add_argument("--description", default="", help="Short project description")
+    p_init.add_argument("--version", default="", help="Current project version")
+
+    # show
+    sub.add_parser("show", help="Print the full context as JSON")
+
+    # inject
+    sub.add_parser("inject", help="Print formatted context for agent system-prompt injection")
+
+    # update
+    p_update = sub.add_parser("update", help="Update a specific context section")
+    p_update.add_argument(
+        "--section", required=True,
+        choices=["decisions", "milestones", "stack", "goals", "banned", "project"],
+        help="Section to update"
+    )
+    p_update.add_argument("--add", help="JSON string or plain string to append")
+    p_update.add_argument("--set", help="JSON object to merge/set (used by stack and project)")
+    p_update.add_argument("--complete", help="Mark a milestone as completed (milestones section)")
+
+    return parser
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    dispatch = {
+        "init": cmd_init,
+        "show": cmd_show,
+        "inject": cmd_inject,
+        "update": cmd_update,
+    }
+    return dispatch[args.command](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())