toolnet-memory 0.2.9 → 0.2.11

package/README.md

@@ -1,97 +1,55 @@
 <div align="center">
 
-# TOOLNET MEMORY
+# ToolNet Memory
 
-### Persistent project memory & code intelligence for AI coding agents
-
-**Continue the same project across OpenCode, Agy and Codex without losing context.**
+### Persistent project memory, work continuity, and code intelligence for AI coding agents
 
 [![npm](https://img.shields.io/npm/v/toolnet-memory?style=flat-square)](https://www.npmjs.com/package/toolnet-memory)
+[![CI](https://github.com/LBT-AI/toolnet-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/LBT-AI/toolnet-memory/actions/workflows/ci.yml)
 [![Node.js](https://img.shields.io/badge/Node.js-22%2B-339933?style=flat-square&logo=node.js&logoColor=white)](https://nodejs.org/)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
 
+**One project. Multiple coding agents. Continuous context.**
+
 </div>
 
 ---
 
-## What does ToolNet Memory do?
-
-ToolNet Memory is a persistent memory layer for AI coding agents.
+## What it does
 
-Its job is simple: **help the next AI understand the project before it continues the work.**
+ToolNet Memory is a persistent memory layer for AI coding workflows. It keeps project knowledge outside any single agent session so Agy / Antigravity, OpenCode, Codex, and MCP-compatible tools can continue work without rebuilding context from zero.
 
-A coding agent normally loses important context when a session ends, tokens run out, you change tools, move to another VPS, or return to the project days later. The new agent may be able to read the source code, but it often does not know the original goal, why an architecture was chosen, what has already been completed, what is still in progress, or which project rules must not be violated.
+It stores durable working context such as:
 
-ToolNet Memory preserves that project knowledge separately from any single AI agent.
-
-```text
-OpenCode stops at Phase 3
-          ↓
-     ToolNet Memory
-          ↓
-Agy opens the same project
-          ↓
-Understands the mission, rationale,
-completed work, current objective,
-constraints and next actions
-          ↓
-Continues Phase 4
-          ↓
-Agy later stops at Phase 6
-          ↓
-     ToolNet Memory
-          ↓
-Codex continues Phase 7
-```
+- project mission and current objective,
+- decisions, rules, blockers, warnings, and next actions,
+- completed and active work,
+- structured session handoff state,
+- semantic project/code context,
+- source symbols, dependencies, architecture, and impact relationships.
 
-It is **not just chat history**. ToolNet extracts and preserves durable working context such as:
-
-- what the project is building,
-- the current objective,
-- why the work matters,
-- why a specific implementation direction was chosen,
-- completed and active phases/tasks,
-- deliverables and Definition of Done,
-- architecture decisions,
-- dependencies and blockers,
-- project operating rules,
-- important warnings,
-- next actions.
-
-The result is a shared technical memory layer between your project and your AI coding agents:
-
-```text
-OpenCode / Agy / Codex
-          ↓
-    ToolNet Memory
-          ↓
-Project Memory + Work State
-+ Semantic Context + Code Intelligence
-          ↓
-The next agent continues with context
-instead of restarting from zero
-```
+ToolNet Memory is **not a raw transcript dump**. Session history and durable project memory are treated separately, and only useful project context should be promoted into long-term memory.
 
----
+## Installation
 
-## Install
+ToolNet Memory is installed **once per VPS/user account**, not once per project.
 
-### Recommended
+Recommended installer:
 
 ```bash
-npx toolnet-memory-install
+curl -fsSL https://memory.toolnet.tech/install | bash
 ```
 
-### One-line installer
+Alternative installer:
 
 ```bash
-curl -fsSL https://memory.toolnet.tech/install | bash
+npx toolnet-memory-install
 ```
 
-### npm
+Or install directly from npm:
 
 ```bash
-npm install -g toolnet-memory
+npm install -g toolnet-memory@latest
 ```
 
 Requires **Node.js 22+**.
@@ -99,422 +57,234 @@ Requires **Node.js 22+**.
 Verify:
 
 ```bash
+toolnet-memory --version
 toolnet-memory doctor
 ```
 
----
+## One-time VPS setup
 
+Global configuration is stored at:
 
-## First-time configuration
+```text
+~/.config/toolnet-memory/.env
+```
 
-After installation, ToolNet Memory can configure storage interactively:
+Run setup once on a new VPS/user account:
 
 ```bash
 toolnet-memory setup
-If Hugging Face storage is already configured, ToolNet detects it and keeps the existing configuration.
-For a new machine, the setup wizard asks for:
-HF_NAMESPACE
-HF_BUCKET
-HF_S3_ACCESS_KEY_ID
-HF_S3_SECRET_ACCESS_KEY
-Configuration is stored at:
-~/.config/toolnet-memory/.env
-Permissions are restricted automatically:
-~/.config/toolnet-memory      700
-~/.config/toolnet-memory/.env 600
-Your Hugging Face credentials belong to your own account and are never bundled with ToolNet Memory.
-The installer can launch this setup automatically on first install.
-

-⸻
-

-## Core capabilities
+```
 
-### Persistent Project Memory
+The setup flow can configure Hugging Face-backed storage and detect supported coding agents. Credentials stay outside project repositories and must never be committed.
 
-Each project gets its own isolated memory universe.
+## Per-project setup
 
-```text
-Project A
-├── memories
-├── vectors
-├── code graph
-├── semantic context
-├── work state
-└── snapshots
-
-Project B
-├── memories
-├── vectors
-├── code graph
-├── semantic context
-├── work state
-└── snapshots
-```
+Each source project gets a stable identity and isolated remote namespace.
 
-Project data does not mix across projects.
+```bash
+cd /path/to/project
 
-### Work Continuity
+toolnet-memory project:manual-init --project "$PWD"
+toolnet-memory index
+```
 
-ToolNet tracks structured execution state such as:
+ToolNet creates project metadata under:
 
 ```text
-Mission
-Objective
-Why
-Plan
-Phase
-Task
-Deliverable
-Definition of Done
-Dependencies
-Decisions
-Blockers
-Warnings
-Next Actions
+.toolnet/
 ```
 
-### Semantic Work Context
-
-ToolNet can preserve:
-
-- project mission,
-- current objective,
-- why the work matters,
-- why a specific approach was chosen,
-- phase objective,
-- deliverables,
-- acceptance criteria,
-- dependencies,
-- constraints,
-- open questions.
+A stable project identity prevents memory from being mixed merely because folders are renamed or moved.
 
-If a reason was never explicitly recorded, ToolNet should not invent one.
-
-### Smart Handoff
-
-When a session ends before the work is complete, ToolNet can preserve a compact handoff containing:
+Remote storage is scoped by project:
 
 ```text
-What we are building
-Why we are building it
-What was completed
-What is currently active
-What remains
-What is blocked
-Important decisions
-Important warnings
-Next actions
+projects/<project-remote>/
+├── memory/
+├── code/
+├── sessions/
+├── work/
+└── snapshots/
 ```
 
-### Project Operating Rules
+## Agent integration
 
-Each project can retain persistent working rules.
+Automatic integration can detect supported agents installed for the current user:
 
-Example:
-
-```text
-ONLY edit:
-/root/project/source
-
-NEVER edit:
-/var/www/project
-
-Deploy only with:
-./deploy.sh --apply
+```bash
+toolnet-memory integrate:auto
 ```
 
-This avoids repeating the same instructions every session or every time you switch agents.
+Or integrate individually:
 
----
+```bash
+toolnet-memory integrate:agy
+toolnet-memory integrate:opencode
+toolnet-memory integrate:codex
+```
 
-## Code Intelligence
+Integration is normally a **one-time user/VPS operation**. Project selection remains automatic through the project's ToolNet identity.
 
-ToolNet builds a project model through:
+After setup, use your coding agent normally:
 
 ```text
-Source Index
-    ↓
-Type Resolution
-    ↓
-Rich Code Graph
-    ↓
-Semantic Code Index
-    ↓
-Architecture Intelligence
-    ↓
-Dependency Analysis
-    ↓
-Impact Analysis
+Agy / Antigravity ─┐
+OpenCode            ├──> ToolNet Memory ──> Project-scoped context
+Codex               ┘
 ```
 
-Capabilities include:
-
-- symbol indexing,
-- type resolution,
-- callers / callees,
-- imports,
-- inheritance,
-- implementations,
-- route detection,
-- architecture layers,
-- subsystem clustering,
-- hotspots,
-- dependency analysis,
-- dead-code candidates,
-- blast radius,
-- semantic code search.
+The intended normal workflow does not require users to manually say “save memory” or “load memory”. Agent/session hooks capture meaningful activity and restore relevant project context at the next session.
 
----
+## Core capabilities
 
-## Quick Start
+### Persistent project memory
 
-Inside a project:
+Durable memory can preserve decisions, rules, todos, fixes, blockers, warnings, architecture changes, and next actions while avoiding unnecessary transcript noise.
 
-```bash
-cd /path/to/project
-toolnet-memory index
-```
+### Work continuity
 
-ToolNet creates a stable project identity:
+Structured continuity can track:
 
 ```text
-.toolnet/project.json
+Mission
+Objective
+Phase
+Task
+Deliverable
+Definition of Done
+Dependencies
+Decisions
+Blockers
+Warnings
+Next Actions
 ```
 
-Moving or renaming the folder does not create a new project identity.
-
-Check project state:
+Useful commands:
 
 ```bash
 toolnet-memory work:status
-```
-
-Generate a startup brief:
-
-```bash
 toolnet-memory brief
+toolnet-memory handoff:latest
 ```
 
-Search semantically:
-
-```bash
-toolnet-memory semantic "authentication flow"
-```
+### Code intelligence
 
-Analyze impact:
+A full index can build:
 
-```bash
-toolnet-memory impact src/path/to/file.ts
+```text
+Source Index
+  ↓
+Type Resolution
+  ↓
+Rich Graph
+  ↓
+Semantic Code Index
+  ↓
+Architecture Intelligence
+  ↓
+Graph Analysis
+  ↓
+Visualization Dataset
 ```
 
----
+Capabilities include symbol indexing, callers/callees, imports, type resolution, architecture layers, subsystem clusters, hotspots, dead-code candidates, semantic search, dependency analysis, and change-impact analysis.
 
-## Main commands
+Examples:
 
 ```bash
-toolnet-memory doctor
-
-toolnet-memory index
-toolnet-memory index:graph
+toolnet-memory semantic "authentication flow"
+toolnet-memory impact src/path/to/file.ts
 toolnet-memory incremental
-
-toolnet-memory semantic "query"
-toolnet-memory impact path/to/file
-
-toolnet-memory brief
-toolnet-memory brief:json
-
-toolnet-memory work:status
-toolnet-memory work:json
-toolnet-memory work:reconcile
-
-toolnet-memory context:sync
-toolnet-memory context:print
-toolnet-memory context:refresh
-
-toolnet-memory snapshot:list
-toolnet-memory snapshot:create "reason"
-toolnet-memory snapshot:restore <id>
-
-toolnet-memory recover
-toolnet-memory mcp
-```
-
-Agent/session integrations include commands for OpenCode, Agy and Codex.
-
----
-
-## Startup Brief
-
-Before an agent continues work, ToolNet can build a compact project brief containing only relevant context:
-
-```text
-PROJECT RULES
-MISSION
-CURRENT OBJECTIVE
-WHY THIS WORK MATTERS
-WHY THIS APPROACH
-ACTIVE WORK
-CURRENT PHASE
-PHASE OBJECTIVE
-DELIVERABLE
-DEFINITION OF DONE
-BLOCKERS
-RECENT DECISIONS
-NEXT ACTIONS
-```
-
-The goal is to avoid dumping entire transcripts into the model.
-
----
-
-## Session Capture
-
-ToolNet can normalize coding-agent sessions into a common project-scoped format.
-
-Sessions can preserve:
-
-```text
-session identity
-messages
-tool activity
-file changes
-continuity observations
-semantic observations
-handoff state
-```
-
-Raw session history and durable long-term memory remain separate.
-
----
-
-## Storage model
-
-Remote project data is isolated by project namespace:
-
-```text
-projects/<project>/
-├── project.json
-├── memory/
-│   ├── records/
-│   └── vectors/
-├── code/
-│   ├── chunks/
-│   ├── vectors/
-│   ├── graph/
-│   ├── architecture/
-│   ├── analysis/
-│   └── visualization/
-├── work/
-├── context/
-└── snapshots/
 ```
 
----
-
-## MCP
+### MCP
 
-ToolNet exposes memory and code intelligence through MCP.
+Expose memory and code intelligence through MCP:
 
 ```bash
 toolnet-memory mcp
 ```
 
-Typical capabilities include memory search, symbol search, dependency lookup, call tracing, architecture context, semantic code search and impact analysis.
+### Snapshots and recovery
 
----
+ToolNet supports project-scoped snapshots and recovery workflows without merging state across projects.
 
-## 3D Code Graph
+## Health and configuration
 
-ToolNet includes a multi-project code graph dashboard.
+Human-readable health check:
 
-```text
-https://memory.toolnet.tech
+```bash
+toolnet-memory doctor
 ```
 
-It can visualize symbols, files, calls, imports, type usage, architecture clusters, dependencies, dead-code candidates and impact relationships.
-
----
+Machine-readable health check:
 
-## Configuration
-
-Global configuration lives at:
-
-```text
-~/.config/toolnet-memory/.env
+```bash
+toolnet-memory doctor --json
 ```
 
-Create it with:
+Read or update global configuration:
 
 ```bash
-mkdir -p ~/.config/toolnet-memory
-chmod 700 ~/.config/toolnet-memory
+toolnet-memory config get KEY
+toolnet-memory config set KEY VALUE
+toolnet-memory config open
 ```
 
-Never commit API keys, tokens or credentials to a repository.
+Secret values are masked in normal CLI output.
 
----
-
-## Update
+## Updating
 
 ```bash
-npm install -g toolnet-memory@latest
+toolnet-memory update
 ```
 
-or rerun:
+The updater checks the latest npm release and updates the global installation.
 
-```bash
-npx toolnet-memory-install
-```
+## Security model
 
-## Uninstall
+ToolNet Memory processes source-code metadata, coding-agent activity, and project memory, so project isolation and secret handling are core requirements.
 
-```bash
-npm uninstall -g toolnet-memory
-```
+- Never commit `.env` files or credentials.
+- Sanitize secrets before durable persistence.
+- Never silently inject memory from another project.
+- Avoid placing full authentication tokens in logs or diagnostics.
+- Treat raw agent transcripts as potentially sensitive.
 
-Local `.toolnet` project metadata is not automatically removed.
-
----
+See [SECURITY.md](SECURITY.md) for vulnerability reporting.
 
 ## Development
 
 ```bash
 git clone https://github.com/LBT-AI/toolnet-memory.git
 cd toolnet-memory
-npm install
-npm run build
+npm ci
 npm test
+npm run build:release
+npm pack --dry-run
 ```
 
-Production build:
+Installer validation:
 
 ```bash
-npm run build:prod
+bash -n scripts/install.sh
 ```
 
----
+See [CONTRIBUTING.md](CONTRIBUTING.md) for repository rules and pull-request requirements.
 
-## Design principles
+## Releases
 
-**Project isolation** — one project must never silently inherit another project's memory.
+CI validates pushes and pull requests. Version tags trigger the release workflow, which validates the package, publishes through npm Trusted Publishing (OIDC), creates the GitHub Release, and attaches the npm tarball.
 
-**Compact context** — agents receive relevant state, not giant transcript dumps.
+The release tag must match `package.json` exactly:
 
-**Provenance** — important semantic state should retain where it came from.
-
-**No invented intent** — missing rationale stays unknown instead of becoming fabricated history.
-
-**Agent independence** — the memory layer is not tied to one coding CLI.
-
-**Graceful failure** — memory/context failures should not break the coding agent itself.
-
----
-
-<div align="center">
+```text
+package.json: 0.2.10
+Git tag:      v0.2.10
+```
 
-### One project. Multiple agents. Continuous memory.
+See [CHANGELOG.md](CHANGELOG.md) for release history.
 
-**ToolNet Memory**
+## License
 
-</div>
+MIT © 2026 LBT-AI. See [LICENSE](LICENSE).