@cognee/cognee-openclaw 2026.3.0 → 2026.3.2

package/README.md

@@ -1,13 +1,32 @@
 # @cognee/cognee-openclaw
 
-OpenClaw plugin that adds Cognee-backed memory with automatic recall and indexing.
+OpenClaw plugin that adds Cognee-backed memory with **multi-scope support** (company/user/agent), session tracking, and automatic recall.
 
 ## Features
 
-- **Auto-recall**: Before each agent run, searches Cognee for relevant memories and injects them as context
-- **Auto-index**: On startup and after each agent run, syncs memory markdown files to Cognee (add new, update changed, delete removed, skip unchanged)
-- **CLI commands**: `openclaw cognee index` to manually sync, `openclaw cognee status` to check state
-- **Configurable**: Search type, max results, score filtering, token limits, and more
+- **Multi-scope memory**: Separate datasets for company-wide knowledge, per-user preferences, and per-agent context
+- **Scope-aware routing**: Memory files are automatically routed to the correct dataset based on directory structure
+- **Multi-scope recall**: Before each agent run, searches across all configured scopes and injects labeled context
+- **Session tracking**: Multi-turn conversation context via Cognee's session system
+- **14 search types**: From simple semantic search (CHUNKS) to chain-of-thought graph reasoning (GRAPH_COMPLETION_COT) to auto-selection (FEELING_LUCKY)
+- **Health check**: Verifies Cognee API connectivity before operations
+- **Auto-index**: Syncs memory markdown files to Cognee (add new, update changed, delete removed, skip unchanged)
+- **Memify support**: Optional graph enrichment after cognify for better entity consolidation
+- **One-command setup**: `openclaw cognee setup` configures Cognee as the sole memory provider
+- **CLI commands**: `openclaw cognee setup`, `openclaw cognee index`, `openclaw cognee status`, `openclaw cognee health`, `openclaw cognee scopes`
+
+## Security: Recommended Plugin Allowlist
+
+OpenClaw will auto-load any plugin it discovers if `plugins.allow` is not set. To restrict which plugins can load, add an explicit allowlist to your `~/.openclaw/openclaw.json`:
+
+```yaml
+plugins:
+  allow:
+    - cognee-openclaw
+    - cognee-openclaw-skills
+```
+
+Without this, any plugin found in your environment could be loaded automatically.
 
 ## Installation
 
@@ -23,12 +42,27 @@ openclaw plugins install -l .
 Or once published:
 
 ```bash
-openclaw plugins install @cognee/cognee-openclaw
+# Pin to an exact version to avoid unintended updates (supply-chain best practice)
+openclaw plugins install @cognee/cognee-openclaw@2026.3.0
 ```
 
-## Configuration
+## Quick Start
+
+After installing, run the setup command to configure Cognee as the memory provider:
 
-Enable the plugin in your OpenClaw config (`~/.openclaw/config.yaml` or project config):
+```bash
+# Cognee only (replaces built-in memory)
+openclaw cognee setup
+
+# Or keep built-in memory alongside Cognee
+openclaw cognee setup --hybrid
+```
+
+**Default mode** disables built-in memory providers — all recall comes from Cognee.
+
+**Hybrid mode** keeps `memory-core` enabled — the agent uses both Cognee recall and built-in memory search.
+
+Then optionally configure the Cognee connection in `~/.openclaw/openclaw.json`:
 
 ```yaml
 plugins:
@@ -39,64 +73,197 @@ plugins:
         baseUrl: "http://localhost:8000"
         apiKey: "${COGNEE_API_KEY}"
         datasetName: "my-project"
-        searchType: "GRAPH_COMPLETION"
-        deleteMode: "hard"
-        maxResults: 6
-        autoRecall: true
-        autoIndex: true
 ```
 
-Set your API key in the environment:
+## Multi-Scope Memory
 
-```bash
-export COGNEE_API_KEY="your-key-here"
+For production use, enable multi-scope mode by setting any scope-specific dataset name:
+
+```yaml
+plugins:
+  entries:
+    cognee-openclaw:
+      enabled: true
+      config:
+        baseUrl: "http://localhost:8000"
+        apiKey: "${COGNEE_API_KEY}"
+
+        # Multi-scope datasets
+        companyDataset: "acme-shared"
+        userDatasetPrefix: "acme-user"
+        agentDatasetPrefix: "acme-agent"
+        userId: "${OPENCLAW_USER_ID}"
+        agentId: "code-assistant"
+
+        # Search all scopes during recall (in priority order)
+        recallScopes:
+          - agent
+          - user
+          - company
+
+        # Default scope for files not matching any route
+        defaultWriteScope: "agent"
+```
+
+### Memory Scope Hierarchy
+
+| Scope | Dataset | Purpose | Example Files |
+|-------|---------|---------|---------------|
+| **Company** | `acme-shared` | Shared knowledge across all users/agents | `memory/company/policies.md`, `memory/company/domain-glossary.md` |
+| **User** | `acme-user-alice` | Per-user preferences, feedback, corrections | `memory/user/preferences.md`, `memory/user/feedback.md` |
+| **Agent** | `acme-agent-code-assistant` | Per-agent learned behaviors, tool outputs | `memory/tools.md`, `MEMORY.md` |
+
+### Scope Routing
+
+Files are routed to scopes based on their path. Default routing rules:
+
+```
+memory/company/**  ->  company scope
+memory/user/**     ->  user scope
+memory/**          ->  agent scope (catch-all)
+MEMORY.md          ->  agent scope
+```
+
+Custom routing via config:
+
+```yaml
+scopeRouting:
+  - pattern: "memory/shared/**"
+    scope: company
+  - pattern: "memory/personal/**"
+    scope: user
+  - pattern: "memory/**"
+    scope: agent
 ```
 
+### Multi-Scope Recall
+
+During recall, the plugin searches each scope independently and injects labeled results:
+
+```xml
+<cognee_memories>
+  <agent_memory>[agent-specific results]</agent_memory>
+  <user_memory>[user preference results]</user_memory>
+  <company_memory>[shared knowledge results]</company_memory>
+</cognee_memories>
+```
+
+This lets the agent distinguish between personal context, shared knowledge, and its own learned patterns.
+
 ## Configuration Options
 
+### Connection
+
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `baseUrl` | string | `http://localhost:8000` | Cognee API base URL |
 | `apiKey` | string | `$COGNEE_API_KEY` | API key for authentication |
-| `datasetName` | string | `openclaw` | Dataset name for storing memories |
-| `searchType` | string | `GRAPH_COMPLETION` | Search mode: `GRAPH_COMPLETION`, `CHUNKS`, `SUMMARIES` |
-| `maxResults` | number | `6` | Max memories to inject per recall |
-| `minScore` | number | `0` | Minimum relevance score filter |
-| `maxTokens` | number | `512` | Token cap for recall context |
+
+### Memory Scopes
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `companyDataset` | string | — | Dataset for company-wide memory. Setting this enables multi-scope mode |
+| `userDatasetPrefix` | string | — | Prefix for user datasets (becomes `{prefix}-{userId}`) |
+| `agentDatasetPrefix` | string | — | Prefix for agent datasets (becomes `{prefix}-{agentId}`) |
+| `userId` | string | `$OPENCLAW_USER_ID` | User identifier for user-scoped memory |
+| `agentId` | string | `default` | Agent identifier for agent-scoped memory |
+| `recallScopes` | string[] | `["agent","user","company"]` | Scopes to search during recall, in priority order |
+| `defaultWriteScope` | string | `agent` | Default scope for files not matching any route |
+| `scopeRouting` | object[] | (see above) | Path-to-scope routing rules |
+
+### Sessions
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enableSessions` | boolean | `true` | Enable session-based conversation tracking |
+| `persistSessionsAfterEnd` | boolean | `true` | Persist session Q&A into the knowledge graph |
+
+### Search
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `searchType` | string | `GRAPH_COMPLETION` | Search strategy (see below) |
+| `maxResults` | number | `3` | Max memories to inject per scope |
+| `minScore` | number | `0.3` | Minimum relevance score filter |
+| `maxTokens` | number | `512` | Token cap for recall context per scope |
+| `searchPrompt` | string | `""` | System prompt to guide search |
+
+### Search Types
+
+| Type | Description |
+|------|-------------|
+| `GRAPH_COMPLETION` | **Default** — graph traversal + LLM reasoning |
+| `CHUNKS` | Semantic vector search, returns raw stored text (no generation) |
+| `FEELING_LUCKY` | Auto-selects a strategy per query (may pick generative modes) |
+| `GRAPH_COMPLETION_COT` | Chain-of-thought reasoning over graph (iterative) |
+| `GRAPH_COMPLETION_CONTEXT_EXTENSION` | Extended context retrieval (multiple rounds) |
+| `GRAPH_SUMMARY_COMPLETION` | Graph with pre-computed summaries |
+| `RAG_COMPLETION` | Traditional RAG with document chunks |
+| `TRIPLET_COMPLETION` | Subject-predicate-object search |
+| `CHUNKS` | Pure semantic vector search |
+| `CHUNKS_LEXICAL` | Keyword/lexical search |
+| `SUMMARIES` | Pre-computed hierarchical summaries |
+| `TEMPORAL` | Time-aware graph search |
+| `NATURAL_LANGUAGE` | Natural language to graph query |
+| `CYPHER` | Direct graph database queries |
+| `CODING_RULES` | Code-specific rule search |
+
+### Automation
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
 | `autoRecall` | boolean | `true` | Inject memories before agent runs |
 | `autoIndex` | boolean | `true` | Sync memory files on startup and after agent runs |
 | `autoCognify` | boolean | `true` | Run cognify after new memories are added |
-| `deleteMode` | string | `soft` | Delete mode: `soft` removes raw data only, `hard` also removes degree-one graph nodes |
-| `searchPrompt` | string | `""` | System prompt sent to Cognee to guide search query processing |
-| `requestTimeoutMs` | number | `60000` | HTTP timeout for Cognee requests |
-| `ingestionTimeoutMs` | number | `300000` | HTTP timeout for add/update (ingestion) requests, which are typically slower |
+| `autoMemify` | boolean | `false` | Run memify (graph enrichment) after cognify |
+| `deleteMode` | string | `soft` | `soft` removes raw data, `hard` also removes graph nodes |
 
-## How It Works
+### Timeouts
 
-1. **On startup**: Scans `memory/` directory for markdown files and syncs to Cognee (add new, update changed, delete removed, skip unchanged)
-2. **Before agent start**: Searches Cognee for memories relevant to the prompt and prepends as `<cognee_memories>` context
-3. **After agent end**: Re-scans memory files and syncs any changes the agent made (including deletions)
-4. **State tracking**:
-   - `~/.openclaw/memory/cognee/datasets.json` — dataset ID mapping
-   - `~/.openclaw/memory/cognee/sync-index.json` — per-file hash and Cognee data IDs
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `requestTimeoutMs` | number | `60000` | HTTP timeout for Cognee requests |
+| `ingestionTimeoutMs` | number | `300000` | HTTP timeout for add/update requests |
 
-Memory files detected at: `MEMORY.md` and `memory/**/*.md` (recursive)
+Note: Files are stored in Cognee using sanitized relative paths as filenames (e.g., `MEMORY.md.txt` for `MEMORY.md`, `memory.tools.md.txt` for `memory/tools.md`) for easy identification and to avoid path separator issues.
 
 ## CLI Commands
 
 ```bash
+# Configure Cognee as the memory provider (run once after install)
+openclaw cognee setup              # Cognee only
+openclaw cognee setup --hybrid     # Cognee + built-in memory
+
 # Manually sync memory files to Cognee
 openclaw cognee index
 
-# Check sync status (indexed files, pending changes)
+# Check sync status (files indexed, dataset info, per-scope breakdown)
 openclaw cognee status
+
+# Verify Cognee API connectivity
+openclaw cognee health
+
+# Show memory scope routing for current workspace files
+openclaw cognee scopes
 ```
 
+## How It Works
+
+1. **On startup**: Health check, then scan `memory/` directory and sync files to scope-specific Cognee datasets
+2. **Before agent start**: Search each configured scope in parallel, merge results with scope labels, inject as `<cognee_memories>` context
+3. **After agent end**: Re-scan memory files and sync any changes (including deletions) to the correct scope datasets
+4. **State tracking**:
+   - `~/.openclaw/memory/cognee/datasets.json` — dataset ID mapping
+   - `~/.openclaw/memory/cognee/scoped-sync-indexes.json` — per-scope file hashes and data IDs
+   - `~/.openclaw/memory/cognee/sync-index.json` — legacy single-scope index
+
+Memory files detected at: `MEMORY.md` and `memory/**/*.md` (recursive)
+
 ## Development
 
 ```bash
 cd integrations/openclaw
-# Build once, then link for local development with an OpenClaw project
 npm install
 npm run build
 openclaw plugins install -l .
@@ -110,8 +277,6 @@ npm run dev
 
 ## Testing
 
-Run the test suite to verify functionality:
-
 ```bash
 npm test
 ```

package/dist/index.d.ts

@@ -1,142 +1,8 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-type CogneeSearchType = "GRAPH_COMPLETION" | "CHUNKS" | "SUMMARIES";
-type CogneeDeleteMode = "soft" | "hard";
-type CogneePluginConfig = {
-    baseUrl?: string;
-    apiKey?: string;
-    username?: string;
-    password?: string;
-    datasetName?: string;
-    searchType?: CogneeSearchType;
-    searchPrompt?: string;
-    deleteMode?: CogneeDeleteMode;
-    maxResults?: number;
-    minScore?: number;
-    maxTokens?: number;
-    autoRecall?: boolean;
-    autoIndex?: boolean;
-    autoCognify?: boolean;
-    requestTimeoutMs?: number;
-    ingestionTimeoutMs?: number;
-};
-type CogneeSearchResult = {
-    id: string;
-    text: string;
-    score: number;
-    metadata?: Record<string, unknown>;
-};
-type SyncIndex = {
-    datasetId?: string;
-    datasetName?: string;
-    entries: Record<string, {
-        hash: string;
-        dataId?: string;
-    }>;
-};
-type MemoryFile = {
-    /** Relative path from workspace root (e.g. "MEMORY.md", "memory/tools.md") */
-    path: string;
-    /** Absolute path on disk */
-    absPath: string;
-    /** File content */
-    content: string;
-    /** SHA-256 hex hash of content */
-    hash: string;
-};
-type SyncResult = {
-    added: number;
-    updated: number;
-    skipped: number;
-    errors: number;
-    deleted: number;
-};
-declare class CogneeClient {
-    private readonly baseUrl;
-    private readonly apiKey?;
-    private readonly username?;
-    private readonly password?;
-    private readonly timeoutMs;
-    private readonly ingestionTimeoutMs;
-    private authToken;
-    private loginPromise;
-    constructor(baseUrl: string, apiKey?: string, username?: string, password?: string, timeoutMs?: number, ingestionTimeoutMs?: number);
-    /**
-     * Authenticate with Cognee via /api/v1/auth/login.
-     * Falls back to default local dev credentials when none are configured.
-     */
-    login(): Promise<void>;
-    /**
-     * Ensure the client is authenticated (login once, reuse token).
-     */
-    ensureAuth(): Promise<void>;
-    private buildHeaders;
-    private fetchJson;
-    add(params: {
-        data: string;
-        datasetName: string;
-        datasetId?: string;
-    }): Promise<{
-        datasetId: string;
-        datasetName: string;
-        dataId?: string;
-    }>;
-    update(params: {
-        dataId: string;
-        datasetId: string;
-        data: string;
-    }): Promise<{
-        datasetId: string;
-        datasetName: string;
-        dataId?: string;
-    }>;
-    /**
-     * Query the dataset's data items and find a matching entry by filename.
-     * Used as fallback when add/update responses don't include a usable data_id.
-     */
-    resolveDataIdFromDataset(datasetId: string, fileName: string): Promise<string | undefined>;
-    delete(params: {
-        dataId: string;
-        datasetId: string;
-        mode?: CogneeDeleteMode;
-    }): Promise<{
-        datasetId: string;
-        dataId: string;
-        deleted: boolean;
-        error?: string;
-    }>;
-    cognify(params?: {
-        datasetIds?: string[];
-    }): Promise<{
-        status?: string;
-    }>;
-    search(params: {
-        queryText: string;
-        searchPrompt: string;
-        searchType: CogneeSearchType;
-        datasetIds: string[];
-        maxTokens: number;
-    }): Promise<CogneeSearchResult[]>;
-    /**
-     * Normalize Cognee search response to consistent format.
-     * Cognee returns a direct array of strings: ["answer text here"]
-     * We convert to: [{ id, text, score }]
-     */
-    private normalizeSearchResults;
-    private extractDataId;
-}
-declare function syncFiles(client: CogneeClient, changedFiles: MemoryFile[], fullFiles: MemoryFile[], syncIndex: SyncIndex, cfg: Required<CogneePluginConfig>, logger: {
-    info?: (msg: string) => void;
-    warn?: (msg: string) => void;
-}): Promise<SyncResult & {
-    datasetId?: string;
-}>;
-declare const memoryCogneePlugin: {
-    id: string;
-    name: string;
-    description: string;
-    kind: "memory";
-    register(api: OpenClawPluginApi): void;
-};
-export default memoryCogneePlugin;
-export { CogneeClient, syncFiles };
-export type { CogneeDeleteMode, CogneePluginConfig, MemoryFile, SyncIndex, SyncResult };
+export { default } from "./src/plugin.js";
+export { CogneeHttpClient } from "./src/client.js";
+export { syncFiles, syncFilesScoped } from "./src/sync.js";
+export { matchGlob, routeFileToScope, datasetNameForScope, isMultiScopeEnabled } from "./src/scope.js";
+export { resolveConfig } from "./src/config.js";
+export { collectMemoryFiles, hashText } from "./src/files.js";
+export { loadDatasetState, saveDatasetState, loadSyncIndex, saveSyncIndex, loadScopedSyncIndexes, saveScopedSyncIndexes, migrateLegacyIndex, } from "./src/persistence.js";
+export type { CogneeDeleteMode, CogneePluginConfig, CogneeSearchType, CogneeSearchResult, MemoryFile, MemoryScope, ScopeRoute, ScopedSyncIndexes, SyncIndex, SyncResult, } from "./src/types.js";