mirror of
https://github.com/outbackdingo/optimclaw.git
synced 2026-09-03 10:09:30 +00:00
5f841554d5
* feat(workspace): add TOOLS.md, BOOTSTRAP.md, and disk-to-DB import Add two new OpenClaw-compatible workspace markdown files: - TOOLS.md: Environment-specific tool notes (SSH hosts, device names, etc.) injected into the system prompt under "## Tool Notes". Seeded as comment-only (like HEARTBEAT.md) so it's effectively empty until the user adds real content. Not write-protected — the agent can update it as it learns the environment. - BOOTSTRAP.md: First-run onboarding ritual. Injected FIRST in the system prompt when present. Guides the agent through introducing itself, learning about the user, and updating workspace files. Only seeded on truly fresh workspaces (no existing identity files) to avoid triggering the ritual on existing deployments. Agent clears it via `memory_write(target="bootstrap")` when done. Add `Workspace::import_from_directory()` for disk-to-DB import: - Scans a directory for *.md files and imports any that don't already exist in the database (never overwrites user edits) - Controlled by WORKSPACE_IMPORT_DIR env var, runs after seed_if_empty() - Enables Docker images / deployment scripts to ship customized workspace templates that override generic seeds - Backwards compatible: no-op when env var is unset Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * fix: address PR review comments - Use stable `path.extension() != Some(OsStr::new("md"))` instead of unstable `is_none_or` (nightly-only) - Use `tokio::join!` for concurrent DB reads in fresh-workspace check - Skip unreadable directory entries instead of failing the entire import - Skip unreadable files instead of failing the entire import Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]>
114 lines
3.9 KiB
Markdown
114 lines
3.9 KiB
Markdown
# Workspace & Memory System
|
|
|
|
Inspired by [OpenClaw](https://github.com/openclaw/openclaw), the workspace provides persistent memory for agents with a flexible filesystem-like structure.
|
|
|
|
## Key Principles
|
|
|
|
1. **"Memory is database, not RAM"** - If you want to remember something, write it explicitly
|
|
2. **Flexible structure** - Create any directory/file hierarchy you need
|
|
3. **Self-documenting** - Use README.md files to describe directory structure
|
|
4. **Hybrid search** - Combines FTS (keyword) + vector (semantic) via Reciprocal Rank Fusion
|
|
|
|
## Filesystem Structure
|
|
|
|
```
|
|
workspace/
|
|
├── README.md <- Root runbook/index
|
|
├── MEMORY.md <- Long-term curated memory
|
|
├── HEARTBEAT.md <- Periodic checklist
|
|
├── IDENTITY.md <- Agent name, nature, vibe
|
|
├── SOUL.md <- Core values
|
|
├── AGENTS.md <- Behavior instructions
|
|
├── USER.md <- User context
|
|
├── TOOLS.md <- Environment-specific tool notes
|
|
├── BOOTSTRAP.md <- First-run ritual (deleted after onboarding)
|
|
├── context/ <- Identity-related docs
|
|
│ ├── vision.md
|
|
│ └── priorities.md
|
|
├── daily/ <- Daily logs
|
|
│ ├── 2024-01-15.md
|
|
│ └── 2024-01-16.md
|
|
├── projects/ <- Arbitrary structure
|
|
│ └── alpha/
|
|
│ ├── README.md
|
|
│ └── notes.md
|
|
└── ...
|
|
```
|
|
|
|
## Using the Workspace
|
|
|
|
```rust
|
|
use crate::workspace::{Workspace, OpenAiEmbeddings, paths};
|
|
|
|
// Create workspace for a user
|
|
let workspace = Workspace::new("user_123", pool)
|
|
.with_embeddings(Arc::new(OpenAiEmbeddings::new(api_key)));
|
|
|
|
// Read/write any path
|
|
let doc = workspace.read("projects/alpha/notes.md").await?;
|
|
workspace.write("context/priorities.md", "# Priorities\n\n1. Feature X").await?;
|
|
workspace.append("daily/2024-01-15.md", "Completed task X").await?;
|
|
|
|
// Convenience methods for well-known files
|
|
workspace.append_memory("User prefers dark mode").await?;
|
|
workspace.append_daily_log("Session note").await?;
|
|
|
|
// List directory contents
|
|
let entries = workspace.list("projects/").await?;
|
|
|
|
// Search (hybrid FTS + vector)
|
|
let results = workspace.search("dark mode preference", 5).await?;
|
|
|
|
// Get system prompt from identity files
|
|
let prompt = workspace.system_prompt().await?;
|
|
```
|
|
|
|
## Memory Tools
|
|
|
|
Four tools for LLM use:
|
|
|
|
- **`memory_search`** - Hybrid search, MUST be called before answering questions about prior work
|
|
- **`memory_write`** - Write to any path (memory, daily_log, or custom paths)
|
|
- **`memory_read`** - Read any file by path
|
|
- **`memory_tree`** - View workspace structure as a tree (depth parameter, default 1)
|
|
|
|
## Hybrid Search (RRF)
|
|
|
|
Combines full-text search and vector similarity using Reciprocal Rank Fusion:
|
|
|
|
```
|
|
score(d) = Σ 1/(k + rank(d)) for each method where d appears
|
|
```
|
|
|
|
Default k=60. Results from both methods are combined, with documents appearing in both getting boosted scores.
|
|
|
|
**Backend differences:**
|
|
- **PostgreSQL:** `ts_rank_cd` for FTS, pgvector cosine distance for vectors, full RRF
|
|
- **libSQL:** FTS5 for keyword search only (vector search via `libsql_vector_idx` not yet wired)
|
|
|
|
## Heartbeat System
|
|
|
|
Proactive periodic execution (default: 30 minutes):
|
|
|
|
1. Reads `HEARTBEAT.md` checklist
|
|
2. Runs agent turn with checklist prompt
|
|
3. If findings, notifies via channel
|
|
4. If nothing, agent replies "HEARTBEAT_OK" (no notification)
|
|
|
|
```rust
|
|
use crate::agent::{HeartbeatConfig, spawn_heartbeat};
|
|
|
|
let config = HeartbeatConfig::default()
|
|
.with_interval(Duration::from_secs(60 * 30))
|
|
.with_notify("user_123", "telegram");
|
|
|
|
spawn_heartbeat(config, workspace, llm, response_tx);
|
|
```
|
|
|
|
## Chunking Strategy
|
|
|
|
Documents are chunked for search indexing:
|
|
- Default: 800 words per chunk (roughly 800 tokens for English)
|
|
- 15% overlap between chunks for context preservation
|
|
- Minimum chunk size: 50 words (tiny trailing chunks merge with previous)
|