toolnet-memory 0.2.10 → 0.2.12

package/README.md

@@ -30,6 +30,43 @@ It stores durable working context such as:
 
 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.
 
+## Quick Start
+
+```bash
+# Install globally (once per VPS/user)
+curl -fsSL https://memory.toolnet.tech/install | bash
+
+# Initialize project
+cd /path/to/project
+toolnet-memory init
+
+# View fast startup context
+toolnet-memory
+```
+
+**Fast Context Output:**
+
+```text
+# Profile
+
+Your development preferences and coding style.
+
+---
+
+# Current Work
+
+Mission: Build authentication system
+Objective: Implement OAuth2 flow
+Phase: Implementation
+Task: Add token refresh logic
+
+Next Actions:
+- [ ] Implement refresh token endpoint
+- [ ] Add token expiry validation
+```
+
+The default command (`toolnet-memory` with no arguments) prints fast startup context from local files only (~150ms, no network/storage access). This provides AI agents with immediate project context at session start.
+
 ## Installation
 
 ToolNet Memory is installed **once per VPS/user account**, not once per project.
@@ -61,6 +98,48 @@ toolnet-memory --version
 toolnet-memory doctor
 ```
 
+## Storage Configuration
+
+ToolNet Memory supports multiple storage backends. **Cloudflare R2 is recommended** for production use due to zero egress fees and S3 compatibility.
+
+### Cloudflare R2 (Recommended)
+
+```bash
+# In ~/.config/toolnet-memory/.env
+STORAGE_PROVIDER=r2
+R2_ACCOUNT_ID=your-account-id
+R2_ACCESS_KEY_ID=your-access-key
+R2_SECRET_ACCESS_KEY=your-secret-key
+R2_BUCKET_NAME=toolnet-memory
+```
+
+### AWS S3 / S3-Compatible
+
+```bash
+STORAGE_PROVIDER=s3
+S3_REGION=us-east-1
+S3_BUCKET=toolnet-memory
+AWS_ACCESS_KEY_ID=your-access-key
+AWS_SECRET_ACCESS_KEY=your-secret-key
+```
+
+### Hugging Face S3 (Legacy)
+
+```bash
+STORAGE_PROVIDER=huggingface
+HF_TOKEN=hf_your_token
+HF_REPO=username/toolnet-memory
+```
+
+### Local Storage
+
+```bash
+STORAGE_PROVIDER=local
+LOCAL_STORAGE_PATH=/path/to/storage
+```
+
+See [docs/STORAGE.md](docs/STORAGE.md) for detailed setup instructions.
+
 ## One-time VPS setup
 
 Global configuration is stored at:
@@ -75,7 +154,7 @@ Run setup once on a new VPS/user account:
 toolnet-memory setup
 ```
 
-The setup flow can configure Hugging Face-backed storage and detect supported coding agents. Credentials stay outside project repositories and must never be committed.
+The setup flow can configure storage backend and detect supported coding agents. Credentials stay outside project repositories and must never be committed.
 
 ## Per-project setup
 
@@ -84,7 +163,12 @@ Each source project gets a stable identity and isolated remote namespace.
 ```bash
 cd /path/to/project
 
+# Initialize project and create agent instruction files
+toolnet-memory init
+
+# Or manually:
 toolnet-memory project:manual-init --project "$PWD"
+toolnet-memory profile:sync
 toolnet-memory index
 ```
 
@@ -92,19 +176,31 @@ ToolNet creates project metadata under:
 
 ```text
 .toolnet/
+├── profile.md      # Your development preferences
+└── current.md      # Current work state
+```
+
+And agent instruction files in the project root:
+
+```text
+GEMINI.md           # Instructions for Gemini/Agy
+AGENTS.md           # Standard agent instructions
+CLAUDE.md           # Instructions for Claude/Codex
 ```
 
+These files provide fast startup context to AI agents without requiring network access or deep memory recovery.
+
 A stable project identity prevents memory from being mixed merely because folders are renamed or moved.
 
 Remote storage is scoped by project:
 
 ```text
 projects/<project-remote>/
-├── memory/
-├── code/
-├── sessions/
-├── work/
-└── snapshots/
+├── memory/         # Persistent project memory
+├── code/           # Code intelligence index
+├── sessions/       # Session transcripts (filtered)
+├── work/           # Work continuity state
+└── snapshots/      # Project snapshots
 ```
 
 ## Agent integration
@@ -133,7 +229,72 @@ OpenCode            ├──> ToolNet Memory ──> Project-scoped context
 Codex               ┘
 ```
 
-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.
+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.
+
+## Fast Context vs Deep Recovery
+
+ToolNet Memory provides two levels of context:
+
+### Fast Context (Default)
+
+Fast context reads only local files (`.toolnet/profile.md`, `.toolnet/current.md`) and completes in ~150ms without network or storage access. This is the default behavior and provides immediate startup context.
+
+```bash
+# Fast context (default command)
+toolnet-memory
+toolnet-memory context:print
+
+# Sync profile and current work to local files
+toolnet-memory profile:sync
+```
+
+### Deep Recovery (Manual Only)
+
+Deep memory recovery fetches full session history and project memory from remote storage. This is **manual only** and not run automatically at agent startup to avoid noise and latency.
+
+```bash
+# Recover last 10 sessions (default limit)
+toolnet-memory session:agy-recover
+
+# Get latest handoff brief
+toolnet-memory handoff:latest
+
+# Full brief with memory
+toolnet-memory brief
+```
+
+Session transcripts are filtered to remove:
+
+- System messages and tool logs
+- npm install/build noise
+- Sensitive data patterns
+- Redundant context
+
+## Example Workflow
+
+```bash
+# 1. Initialize project
+cd /path/to/project
+toolnet-memory init
+
+# 2. Start coding with your agent
+agy "implement user authentication"
+
+# 3. Fast context is automatically injected at session start
+# Agent sees profile.md + current.md (~150ms)
+
+# 4. Work continues across sessions
+codex "add password reset flow"
+
+# 5. Query semantic code context
+toolnet-memory semantic "auth flow"
+
+# 6. Check change impact
+toolnet-memory impact src/auth.ts
+
+# 7. Manual deep recovery if needed
+toolnet-memory session:agy-recover --limit 5
+```
 
 ## Core capabilities
 
@@ -250,6 +411,7 @@ ToolNet Memory processes source-code metadata, coding-agent activity, and projec
 - Never silently inject memory from another project.
 - Avoid placing full authentication tokens in logs or diagnostics.
 - Treat raw agent transcripts as potentially sensitive.
+- Storage credentials are stored in `~/.config/toolnet-memory/.env` (never in project repos).
 
 See [SECURITY.md](SECURITY.md) for vulnerability reporting.
 
@@ -259,6 +421,9 @@ See [SECURITY.md](SECURITY.md) for vulnerability reporting.
 git clone https://github.com/LBT-AI/toolnet-memory.git
 cd toolnet-memory
 npm ci
+npm run lint
+npm run format:check
+npm run typecheck
 npm test
 npm run build:release
 npm pack --dry-run

package/bin/toolnet-memory

@@ -19,7 +19,7 @@ if [ "${1:-}" = "--version" ] || [ "${1:-}" = "-v" ]; then
   exit 0
 fi
 
-COMMAND="${1:-help}"
+COMMAND="${1:-context:print}"
 
 run() {
   DIST="$1"
@@ -269,6 +269,50 @@ case "$COMMAND" in
     exit 1
     ;;
 
+  memory:review)
+    shift
+
+    if [ -x "${TSX:-}" ]; then
+      exec "$TSX" "$ROOT/src/session/memory-review-cli.ts" "$@"
+    fi
+
+    echo "Memory review not available."
+    exit 1
+    ;;
+
+  guard:check)
+    shift
+
+    if [ -x "${TSX:-}" ]; then
+      exec "$TSX" "$ROOT/src/guard/cli.ts" "$@"
+    fi
+
+    echo "Guard not available."
+    exit 1
+    ;;
+
+  guard:explain)
+    shift
+
+    if [ -x "${TSX:-}" ]; then
+      exec "$TSX" "$ROOT/src/guard/cli.ts" "$@"
+    fi
+
+    echo "Guard not available."
+    exit 1
+    ;;
+
+  guard:json)
+    shift
+
+    if [ -x "${TSX:-}" ]; then
+      exec "$TSX" "$ROOT/src/guard/cli.ts" --json "$@"
+    fi
+
+    echo "Guard not available."
+    exit 1
+    ;;
+
   project:manual-init)
     shift
 
@@ -389,6 +433,26 @@ case "$COMMAND" in
     exec "$TSX" "$ROOT/src/work-continuity/context-runtime-cli.ts" refresh "$@"
     ;;
 
+  profile:show)
+    shift
+
+    if [ -f "$ROOT/bundle/context-runtime.js" ]; then
+      exec node "$ROOT/bundle/context-runtime.js" profile-show "$@"
+    fi
+
+    exec "$TSX" "$ROOT/src/work-continuity/context-runtime-cli.ts" profile-show "$@"
+    ;;
+
+  profile:sync)
+    shift
+
+    if [ -f "$ROOT/bundle/context-runtime.js" ]; then
+      exec node "$ROOT/bundle/context-runtime.js" profile-sync "$@"
+    fi
+
+    exec "$TSX" "$ROOT/src/work-continuity/context-runtime-cli.ts" profile-sync "$@"
+    ;;
+
   session:codex-context)
     shift
 
@@ -405,9 +469,56 @@ case "$COMMAND" in
 
   help|--help|-h)
     cat <<'HELP'
-ToolNet Memory
+ToolNet Memory - Project Context & Memory System
+
+FAST CONTEXT (default):
+  toolnet-memory                          Print fast project context (default)
+  toolnet-memory context:print            Print fast project context
+  toolnet-memory context:sync             Show context hash/size
+  toolnet-memory profile:show             Show .toolnet/profile.md
+  toolnet-memory profile:sync             Sync profile to GEMINI.md/AGENTS.md/CLAUDE.md
+
+MANUAL DEEP RECOVERY (do not run automatically):
+  toolnet-memory context:refresh          Rebuild deep startup brief cache
+  toolnet-memory brief [--tokens N]       Show full project brief
+  toolnet-memory handoff:latest           Show latest session handoff
+  toolnet-memory session:agy-recover [--limit N]      Recover Agy sessions
+  toolnet-memory session:codex-recover [--limit N]    Recover Codex sessions
+  toolnet-memory session:opencode-recover [--limit N] Recover OpenCode sessions
+
+MEMORY OPERATIONS:
+  toolnet-memory memory:review [--project PATH] [--session ID]
+  toolnet-memory memory:reconcile [--project PATH]
+
+GUARD (Architecture & Rule Checking):
+  toolnet-memory guard:check                    Check project rules and evidence
+  toolnet-memory guard:check --file <path>      Check if file violates rules
+  toolnet-memory guard:check --command "<cmd>"  Check if command is dangerous
+  toolnet-memory guard:explain                  Show rules and evidence
+  toolnet-memory guard:json                     Output guard result as JSON
+
+NOTE: Raw transcripts are not injected into prompts.
+      Durable memory is promoted selectively based on importance scoring.
+      Guard mode: warn (default), strict, or off (TOOLNET_GUARD_MODE)
+
+PROJECT MANUAL:
+  toolnet-memory project:manual-init [--project PATH]
+  toolnet-memory project:manual-show [--project PATH]
+  toolnet-memory project:manual-sync [--project PATH]
+
+WORK CONTINUITY:
+  toolnet-memory work:status [--project PATH]
+  toolnet-memory work:json [--project PATH]
+  toolnet-memory work:reconcile [--project PATH]
 
-Commands:
+CODE INTELLIGENCE:
+  toolnet-memory index
+  toolnet-memory index:graph
+  toolnet-memory incremental
+  toolnet-memory semantic "query"
+  toolnet-memory impact [file]
+
+SETUP & INTEGRATION:
   toolnet-memory --version
   toolnet-memory doctor
   toolnet-memory setup
@@ -415,36 +526,26 @@ Commands:
   toolnet-memory config get KEY
   toolnet-memory config set KEY VALUE
   toolnet-memory config open
-  toolnet-memory index
-  toolnet-memory index:graph
-  toolnet-memory incremental
-  toolnet-memory semantic "query"
-  toolnet-memory impact [file]
-  toolnet-memory mcp
   toolnet-memory integrate:auto
+  toolnet-memory integrate:opencode
+  toolnet-memory integrate:agy
+  toolnet-memory integrate:codex
+  toolnet-memory mcp
+
+SNAPSHOTS:
   toolnet-memory snapshot:list
   toolnet-memory snapshot:create "reason"
   toolnet-memory snapshot:restore <id>
   toolnet-memory recover
-  toolnet-memory integrate:opencode
-  toolnet-memory integrate:agy
-  toolnet-memory integrate:codex
-  toolnet-memory session:codex-sync <thread-id>
-  toolnet-memory session:codex-recover [--limit N]
-  toolnet-memory memory:reconcile [--project PATH]
-  toolnet-memory project:manual-init [--project PATH]
-  toolnet-memory project:manual-show [--project PATH]
-  toolnet-memory project:manual-sync [--project PATH]
-  toolnet-memory work:status [--project PATH]
-  toolnet-memory work:json [--project PATH]
-  toolnet-memory work:reconcile [--project PATH]
-  toolnet-memory brief [--project PATH] [--tokens N]
-  toolnet-memory brief:json [--project PATH] [--tokens N]
-  toolnet-memory handoff:latest [--project PATH]
+
+SESSION SYNC (manual):
   toolnet-memory session:agy-sync <conversation-id> --transcript <path>
-  toolnet-memory session:agy-recover [--limit N]
+  toolnet-memory session:codex-sync <thread-id>
   toolnet-memory session:opencode-sync <session-id>
-  toolnet-memory session:opencode-recover [--limit N]
+
+IMPORTANT:
+Deep recovery commands (brief, handoff:latest, session:*-recover) are manual only.
+Do not run them automatically at startup. Use fast context commands instead.
 HELP
     ;;