@sesamespace/hivemind 0.10.0 → 0.11.0

package/MEMORY-ENHANCEMENT-PLAN.md

@@ -0,0 +1,211 @@
+# Memory Enhancement Plan — Automatic Context Management
+
+## Vision
+Transform Hivemind's memory system from passive storage to active context management. Background processes continuously organize, index, and surface relevant information without agent intervention.
+
+## Core Enhancements
+
+### 1. Code Context Tracking
+**Background Process:** `code-indexer`
+- Monitors file access patterns (which files the agent reads/writes)
+- Extracts key structures: functions, classes, interfaces, schemas
+- Maintains a "working set" of active code elements
+- Updates git commit context automatically
+- Indexes by: project, language, purpose, last-accessed
+
+**Data Structure:**
+```json
+{
+  "type": "code_context",
+  "project": "hivemind",
+  "file": "packages/runtime/src/agent.ts",
+  "elements": [
+    {
+      "name": "processMessage",
+      "type": "function",
+      "signature": "(msg: Message): Promise<Response>",
+      "purpose": "Core message processing loop",
+      "dependencies": ["memory-client", "router"]
+    }
+  ],
+  "last_accessed": "2024-01-15T10:30:00Z",
+  "access_count": 15,
+  "git_context": {
+    "branch": "feature/memory-enhancement",
+    "last_commit": "abc123",
+    "modified": true
+  }
+}
+```
+
+### 2. Web Research Digestion
+**Background Process:** `research-digester`
+- Monitors web fetch/browse operations
+- Extracts key concepts, APIs, solutions
+- Links research to active tasks/projects
+- Builds knowledge graph of related concepts
+- Identifies patterns across multiple sources
+
+**Data Structure:**
+```json
+{
+  "type": "research_insight",
+  "url": "https://docs.example.com/api",
+  "project": "sesame-integration",
+  "extracted": {
+    "key_concepts": ["OAuth flow", "webhook endpoints"],
+    "code_examples": ["const auth = await getToken()..."],
+    "warnings": ["Rate limit: 100 req/min"],
+    "related_to": ["auth-implementation", "rate-limiting"]
+  },
+  "timestamp": "2024-01-15T09:00:00Z",
+  "referenced_count": 3
+}
+```
+
+### 3. Task State Management
+**Background Process:** `task-tracker`
+- Monitors agent actions and maps to task progress
+- Detects task transitions (started, blocked, completed)
+- Tracks dependencies and blockers
+- Identifies patterns in task completion
+- Surfaces relevant context when returning to a task
+
+**Data Structure:**
+```json
+{
+  "type": "task_state",
+  "id": "implement-dashboard",
+  "project": "hivemind",
+  "status": "in_progress",
+  "progress": {
+    "completed": ["setup routes", "basic UI"],
+    "current": "implement request filtering",
+    "next": ["add export functionality", "write tests"]
+  },
+  "context": {
+    "key_files": ["src/dashboard/server.js", "src/dashboard/index.html"],
+    "recent_decisions": ["use server-sent events for real-time updates"],
+    "blockers": [],
+    "time_spent": "3.5 hours"
+  },
+  "last_updated": "2024-01-15T11:00:00Z"
+}
+```
+
+### 4. Tool Usage Patterns
+**Background Process:** `command-learner`
+- Tracks successful command sequences
+- Identifies common patterns and workflows
+- Builds "recipes" for common tasks
+- Learns from failures and corrections
+- Suggests optimizations
+
+**Data Structure:**
+```json
+{
+  "type": "tool_pattern",
+  "name": "github-push-workflow",
+  "triggers": ["git push", "push changes"],
+  "sequence": [
+    {"tool": "git_status", "check": "has_changes"},
+    {"tool": "git_add", "params": {"files": "."}}
+    {"tool": "git_commit", "params": {"message": "<generated>"}},
+    {"tool": "git_push", "params": {"remote": "origin"}}
+  ],
+  "success_rate": 0.95,
+  "last_used": "2024-01-15T10:00:00Z",
+  "variations": ["with-specific-files", "force-push"]
+}
+```
+
+### 5. Cross-Agent Awareness
+**Background Process:** `agent-sync`
+- Monitors Sesame channels for other agent activity
+- Extracts "public knowledge" from agent interactions
+- Tracks handoff points and collaboration patterns
+- Maintains agent capability registry
+- Identifies complementary skills
+
+**Data Structure:**
+```json
+{
+  "type": "agent_knowledge",
+  "agent": "bailey",
+  "capabilities": ["rust development", "system architecture"],
+  "current_focus": ["hivemind dashboard", "memory optimization"],
+  "collaboration_points": [
+    {
+      "task": "dashboard-implementation",
+      "status": "bailey-implementing",
+      "handoff_ready": "2024-01-16"
+    }
+  ],
+  "last_seen": "2024-01-15T11:30:00Z"
+}
+```
+
+## Implementation Architecture
+
+### Background Process Framework
+```typescript
+interface BackgroundProcess {
+  name: string;
+  interval: number; // milliseconds
+  async run(context: ProcessContext): Promise<void>;
+  async shouldRun(context: ProcessContext): Promise<boolean>;
+}
+
+class ProcessManager {
+  private processes: Map<string, BackgroundProcess>;
+  private memory: MemoryClient;
+  
+  async start() {
+    for (const [name, process] of this.processes) {
+      setInterval(async () => {
+        if (await process.shouldRun(this.context)) {
+          await process.run(this.context);
+        }
+      }, process.interval);
+    }
+  }
+}
+```
+
+### Memory Indexing Strategy
+1. **Write-through cache**: All observations written immediately to L2
+2. **Background indexing**: Processes run every 30s-5min depending on type
+3. **Smart batching**: Group related updates to minimize memory churn
+4. **Relevance scoring**: Continuously update scores based on access patterns
+5. **Compression**: Older entries compressed/summarized, recent kept detailed
+
+### Context Injection
+When building LLM prompts, the system will:
+1. Query active task state
+2. Include relevant code context (files, functions being worked on)
+3. Add recent research/documentation insights
+4. Include tool patterns for likely next actions
+5. Add cross-agent awareness if collaborating
+
+### Local Processing Power Usage
+- **Embedding generation**: Ollama with local models (no API calls)
+- **Pattern matching**: Rust-based processors for speed
+- **Index management**: LanceDB for vector operations
+- **File watching**: Native OS APIs for efficiency
+- **Git operations**: libgit2 bindings for speed
+
+## Benefits
+1. **Zero cognitive load**: Agents don't think about memory management
+2. **Rich context**: Every request includes highly relevant information
+3. **Learning system**: Gets better at predicting needed context over time
+4. **Collaborative**: Agents automatically aware of each other's work
+5. **Efficient**: Background processing keeps LLM calls focused
+
+## Next Steps
+1. Implement the background process framework in TypeScript
+2. Create the first processor: `code-indexer`
+3. Test with real agent workflows
+4. Add remaining processors incrementally
+5. Optimize based on dashboard metrics
+
+This system will make every Hivemind agent dramatically more capable without any changes to their prompts or behavior.

package/TOOL-USE-DESIGN.md

@@ -0,0 +1,173 @@
+# Hivemind Tool Use — Architecture Design
+
+## Current State
+
+The LLM client does simple chat completions: `messages[] → response.content`. No tool/function calling.
+
+## Goal
+
+Full agentic tool-use loop matching OpenClaw capabilities, with Hivemind's memory system as a differentiator.
+
+## Architecture
+
+### 1. Tool Calling Protocol (OpenAI-compatible, works with OpenRouter)
+
+The OpenAI chat completions API supports `tools` (function definitions) and `tool_choice`. When the model wants to use a tool, it returns a `tool_calls` array instead of (or alongside) content. We then execute the tool, append the result as a `tool` role message, and call the model again.
+
+```
+User message
+    ↓
+LLM (with tools defined)
+    ↓
+If tool_calls → execute tools → append results → call LLM again (loop)
+If content only → return response
+```
+
+This is a **while loop**, not a single call. The model may chain multiple tool calls before producing a final text response.
+
+### 2. Key Data Structures
+
+```typescript
+interface ToolDefinition {
+  name: string;
+  description: string;
+  parameters: JSONSchema;  // JSON Schema for function params
+}
+
+interface ToolCall {
+  id: string;
+  type: "function";
+  function: { name: string; arguments: string };  // arguments is JSON string
+}
+
+interface ToolResult {
+  tool_call_id: string;
+  role: "tool";
+  content: string;  // result as string
+}
+
+// Extended message types
+interface AssistantMessage {
+  role: "assistant";
+  content: string | null;
+  tool_calls?: ToolCall[];
+}
+
+interface ToolMessage {
+  role: "tool";
+  tool_call_id: string;
+  content: string;
+}
+```
+
+### 3. Tool Registry
+
+A simple registry where tools are registered with:
+- Name
+- Description (for the LLM)
+- JSON Schema for parameters
+- Executor function: `(params: any) => Promise<string>`
+
+```typescript
+class ToolRegistry {
+  private tools: Map<string, { def: ToolDefinition; exec: (params: any) => Promise<string> }>;
+  
+  register(name, description, schema, executor): void;
+  getDefinitions(): ToolDefinition[];  // For LLM API call
+  execute(name: string, params: any): Promise<string>;  // Run a tool
+}
+```
+
+### 4. The Agentic Loop (in Agent.processMessage)
+
+```
+1. Build messages (system + history + user)
+2. Call LLM with tools
+3. While response has tool_calls:
+   a. For each tool_call: execute, collect result
+   b. Append assistant message (with tool_calls) to messages
+   c. Append tool result messages
+   d. Call LLM again with updated messages
+4. Return final text content
+5. Store in memory (include tool usage summary)
+```
+
+**Safety limits:**
+- Max iterations per turn (e.g., 25)
+- Max total tokens per turn
+- Tool execution timeout (per tool)
+- Dangerous command confirmation (optional)
+
+### 5. Phase 1 Tools
+
+#### `shell` (exec)
+- Run a shell command, return stdout/stderr
+- Working directory: `~/hivemind/workspace`
+- Timeout: 30s default, configurable
+- Safety: no `rm -rf /` etc.
+
+#### `read_file`
+- Read file contents (with optional offset/limit for large files)
+- Returns text content or error
+
+#### `write_file`
+- Write content to a file (creates dirs if needed)
+- Returns success/failure
+
+#### `edit_file`
+- Find and replace exact text in a file
+- oldText → newText pattern (surgical edits)
+
+#### `web_search`
+- Search via Brave API
+- Returns titles, URLs, snippets
+
+#### `web_fetch`
+- Fetch URL, extract markdown
+- Returns readable content
+
+### 6. Memory Integration
+
+Tool calls and results should be stored in memory, but summarized:
+- Don't store full file contents in L2 episodes
+- Store: "Used shell to run `git status`, found 3 modified files"
+- L3 promotion can learn patterns: "For git operations, agent uses shell tool"
+
+### 7. Config
+
+```toml
+[tools]
+enabled = true
+max_iterations = 25
+shell_timeout_s = 30
+workspace = "workspace"
+
+[tools.web_search]
+api_key = ""  # or from vault
+```
+
+### 8. Implementation Order
+
+1. **ToolRegistry class** — registration, definitions, execution
+2. **LLMClient.chatWithTools()** — extended chat that handles tool_calls
+3. **Agentic loop in Agent** — the while loop with safety limits
+4. **shell tool** — most impactful, enables everything
+5. **File tools** — read/write/edit
+6. **Web tools** — search/fetch
+7. **Memory integration** — summarize tool usage in episodes
+
+### 9. OpenRouter Compatibility
+
+OpenRouter passes through tool definitions to the underlying model. Most models support tools:
+- Claude: Native tool_use
+- GPT-4: Native function_calling
+- Gemini: Native function declarations
+
+The OpenAI-compatible format works for all of them through OpenRouter.
+
+### 10. Safety Considerations
+
+- **Sandbox**: Tools run on the agent's machine. File access should be scoped to workspace.
+- **Confirmation**: Optionally require human approval for destructive operations.
+- **Logging**: All tool calls logged to request logger for debugging.
+- **Rate limiting**: Prevent runaway tool loops.

package/dist/{chunk-FBQBBAPZ.js → chunk-4C6B2AMB.js}

@@ -1,6 +1,6 @@
 import {
   FleetManager
-} from "./chunk-IXBIAX76.js";
+} from "./chunk-K6KL2VD6.js";
 
 // packages/cli/src/commands/fleet.ts
 function formatUptime(seconds) {
@@ -183,4 +183,4 @@ Commands:
 export {
   runFleetCommand
 };
-//# sourceMappingURL=chunk-FBQBBAPZ.js.map
+//# sourceMappingURL=chunk-4C6B2AMB.js.map

package/dist/{chunk-FK6WYXRM.js → chunk-4YXOQGQC.js}

@@ -1,7 +1,7 @@
 import {
   SesameClient,
   getClaudeCodeOAuthToken
-} from "./chunk-M3A2WRXM.js";
+} from "./chunk-OB6OXLPC.js";
 
 // packages/cli/src/commands/init.ts
 import { resolve, dirname } from "path";
@@ -436,4 +436,4 @@ Options:
 export {
   runInitCommand
 };
-//# sourceMappingURL=chunk-FK6WYXRM.js.map
+//# sourceMappingURL=chunk-4YXOQGQC.js.map

package/dist/{chunk-IXBIAX76.js → chunk-K6KL2VD6.js}

@@ -7,7 +7,7 @@ import {
   SesameClient2 as SesameClient,
   WORKER_ROUTES,
   createLogger
-} from "./chunk-M3A2WRXM.js";
+} from "./chunk-OB6OXLPC.js";
 
 // packages/runtime/src/watchdog.ts
 import { execSync } from "child_process";
@@ -1095,4 +1095,4 @@ export {
   WorkerMemorySync,
   PrimaryMemorySync
 };
-//# sourceMappingURL=chunk-IXBIAX76.js.map
+//# sourceMappingURL=chunk-K6KL2VD6.js.map

package/dist/{chunk-BHCDOHSK.js → chunk-LYL5GG2F.js}

@@ -1,10 +1,10 @@
 import {
   Watchdog
-} from "./chunk-IXBIAX76.js";
+} from "./chunk-K6KL2VD6.js";
 import {
   defaultSentinelConfig,
   loadConfig
-} from "./chunk-M3A2WRXM.js";
+} from "./chunk-OB6OXLPC.js";
 
 // packages/cli/src/commands/watchdog.ts
 import { resolve } from "path";
@@ -76,4 +76,4 @@ Options:
 export {
   runWatchdogCommand
 };
-//# sourceMappingURL=chunk-BHCDOHSK.js.map
+//# sourceMappingURL=chunk-LYL5GG2F.js.map