add changes to docs and test
This commit is contained in:
1 parent
c71eca5237
commit
e8b4540c25
4 files changed
+75
-562
No files matched your search
+16
-210
@@ -1,66 +1,37 @@
|
||||
---
|
||||
summary: "Cognee knowledge graph memory: setup, Docker config, and usage"
|
||||
summary: "Cognee memory quick setup and usage"
|
||||
read_when:
|
||||
- Setting up Cognee memory provider
|
||||
- Configuring knowledge graph memory
|
||||
- Running Cognee with Docker
|
||||
---
|
||||
|
||||
# Cognee Memory Provider
|
||||
|
||||
MoltBot supports [**Cognee**](https://www.cognee.ai/) as an optional memory provider. Unlike the default SQLite-based vector memory, Cognee builds a knowledge graph with entity extraction and semantic relationships, providing richer contextual memory for your AI agent.
|
||||
Moltbot supports [Cognee](https://www.cognee.ai/) - [open source AI memory](https://github.com/topoteretes/cognee) - as an optional memory provider. Cognee builds knowledge graph memory backed by embeddings from any data and can be run locally with Docker. Learn more from [Cognee Documentation](https://docs.cognee.ai/).
|
||||
|
||||
## What is Cognee?
|
||||
## Quickstart with Docker
|
||||
|
||||
Cognee is an [open source AI memory](https://github.com/topoteretes/cognee) framework that:
|
||||
- Ingests unstructured/structured data from 30+ sources
|
||||
- Extracts entities (people, places, concepts) from documents
|
||||
- Builds a knowledge graph of relationships backed by embeddings
|
||||
- Enables semantic search with LLM-powered reasoning
|
||||
- Supports multiple search modes (e.g., GRAPH_COMPLETION, chunks, summaries)
|
||||
|
||||
Learn more at [docs.cognee.ai](https://docs.cognee.ai/).
|
||||
|
||||
## Setup Options
|
||||
|
||||
### Option 1: Local Docker (Recommended)
|
||||
|
||||
Use the repo example compose file:
|
||||
Run the example compose file:
|
||||
|
||||
```bash
|
||||
docker compose -f examples/cognee-docker-compose.yaml up -d
|
||||
```
|
||||
|
||||
This binds to `127.0.0.1:8000`, so Cognee is only reachable from your machine.
|
||||
|
||||
**Verify:**
|
||||
Verify:
|
||||
|
||||
```bash
|
||||
curl http://localhost:8000/health
|
||||
```
|
||||
|
||||
You can use `http://localhost:8000/docs` to register user and login to get your token.
|
||||
|
||||
### Option 2: Cognee Cloud
|
||||
|
||||
Use the hosted Cognee service:
|
||||
|
||||
1. Sign up at [platform.cognee.ai](https://platform.cognee.ai/)
|
||||
2. Get your API key from the dashboard
|
||||
3. Use base URL: `https://cognee--cognee-saas-backend-serve.modal.run`
|
||||
|
||||
## Configuration
|
||||
|
||||
Moltbot reads `~/.clawdbot/moltbot.json` (JSON5). For local + secure setup, use an env var for the Cognee token and reference it in config.
|
||||
|
||||
### Step 1: Put tokens in `~/.clawdbot/.env`
|
||||
Put the token in `~/.clawdbot/.env`:
|
||||
|
||||
```bash
|
||||
COGNEE_API_KEY="your-cognee-access-token"
|
||||
CLAWDBOT_GATEWAY_TOKEN="your-random-gateway-token"
|
||||
```
|
||||
|
||||
### Step 2: Configure Cognee in `~/.clawdbot/moltbot.json`
|
||||
Configure `~/.clawdbot/moltbot.json` (JSON5):
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -86,195 +57,30 @@ CLAWDBOT_GATEWAY_TOKEN="your-random-gateway-token"
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Start the gateway with env loaded
|
||||
Start the gateway with env loaded:
|
||||
|
||||
```zsh
|
||||
set -a; source "$HOME/.clawdbot/.env"; set +a
|
||||
pnpm moltbot gateway --port 18789 --token "$CLAWDBOT_GATEWAY_TOKEN" --verbose
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Configuration Options
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `baseUrl` | string | `http://localhost:8000` | Cognee API endpoint |
|
||||
| `apiKey` | string | - | Access token (required if Cognee auth is enabled) |
|
||||
| `datasetName` | string | `"clawdbot"` | Dataset name for organizing memories |
|
||||
| `searchType` | string | `"GRAPH_COMPLETION"` | Search mode: `GRAPH_COMPLETION`, `chunks`, or `summaries` |
|
||||
| `maxResults` | number | `6` | Maximum search results returned |
|
||||
| `autoCognify` | boolean | `true` | Auto-process documents after adding |
|
||||
| `cognifyBatchSize` | number | `100` | Batch size for processing |
|
||||
| `timeoutSeconds` | number | `180` | Request timeout in seconds |
|
||||
|
||||
## Search Types
|
||||
|
||||
Cognee offers these modes. GRAPH_COMPLETION is the default mode.
|
||||
|
||||
Learn more from [cognee documentation](https://docs.cognee.ai/core-concepts/main-operations/search)
|
||||
|
||||
## Usage
|
||||
|
||||
### Memory Files
|
||||
Cognee indexes `MEMORY.md` in workspace root, `memory/*.md`, and session transcripts when `sources: ["sessions"]` is enabled.
|
||||
|
||||
Cognee automatically syncs your memory files:
|
||||
- `MEMORY.md` or `memory.md` in workspace root
|
||||
- All `*.md` files in `memory/` directory
|
||||
|
||||
### Session Transcripts (Optional)
|
||||
|
||||
Enable session memory to index conversation history:
|
||||
|
||||
```yaml
|
||||
agents:
|
||||
defaults:
|
||||
memorySearch:
|
||||
provider: cognee
|
||||
sources: [memory, sessions] # Include sessions
|
||||
experimental:
|
||||
sessionMemory: true
|
||||
```
|
||||
|
||||
### Manual Sync and Status
|
||||
1. Initial index and status:
|
||||
|
||||
```bash
|
||||
# Manually sync cognee memory for the current agent
|
||||
pnpm moltbot memory status --index --json
|
||||
```
|
||||
|
||||
## How It Works
|
||||
2. Memory updates:
|
||||
|
||||
1. **Add**: Memory files are sent to Cognee with metadata
|
||||
2. **Cognify**: Cognee processes documents:
|
||||
- Extracts entities (people, places, concepts)
|
||||
- Identifies relationships
|
||||
- Builds knowledge graph
|
||||
3. **Search**: Agent queries use semantic search:
|
||||
- Searches knowledge graph
|
||||
- Returns relevant insights/chunks/summaries
|
||||
- Includes metadata and scores
|
||||
|
||||
## Comparison: Cognee vs SQLite Memory
|
||||
|
||||
| Feature | Cognee | SQLite (Default) |
|
||||
|---------|--------|------------------|
|
||||
| **Setup** | Requires Docker/cloud | Built-in, no setup |
|
||||
| **Offline** | Yes (Optional cloud) | Yes (fully local) |
|
||||
| **Search** | Knowledge graph + LLM | Vector + BM25 hybrid |
|
||||
| **Entities** | Extracted automatically | Not available |
|
||||
| **Relationships** | Yes (graph-based) | No |
|
||||
| **Speed** | Slower (API calls) | Faster (local DB) |
|
||||
| **Memory** | Stored locally (Optional cognee configs) | SQLite file |
|
||||
| **Best for** | Rich context, reasoning | Fast lookup, privacy |
|
||||
```bash
|
||||
pnpm moltbot memory status --index --update-cognee --json
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Failed
|
||||
|
||||
**Error**: `Failed to connect to Cognee at http://localhost:8000`
|
||||
|
||||
**Solutions**:
|
||||
1. Verify Docker is running: `docker ps | grep cognee`
|
||||
2. Check Cognee logs: `docker logs cognee`
|
||||
3. Test manually: `curl http://localhost:8000/health`
|
||||
4. Ensure port 8000 is not blocked
|
||||
|
||||
### Slow Performance
|
||||
|
||||
**Solutions**:
|
||||
1. Reduce `maxResults` (try 3-5 instead of 10+)
|
||||
2. Use `searchType: "chunks"` for faster results
|
||||
3. Set `autoCognify: false` and cognify manually
|
||||
4. Check Docker resource limits
|
||||
|
||||
### Out of Memory
|
||||
|
||||
**Solutions**:
|
||||
1. Increase Docker memory limit (Docker Desktop settings)
|
||||
2. Reduce `cognifyBatchSize` (try 50 instead of 100)
|
||||
3. Process fewer files at once
|
||||
4. Clear old datasets via Cognee API
|
||||
|
||||
### 401 Unauthorized (Cognee auth)
|
||||
|
||||
**Cause**: Cognee auth is enabled, but Moltbot is missing/using an invalid `COGNEE_API_KEY`.
|
||||
|
||||
**Fix**:
|
||||
1. Log in to Cognee and get a fresh access token.
|
||||
2. Update `COGNEE_API_KEY` in `.clawd/.env`.
|
||||
3. Restart the gateway with env loaded (see Step 3 above).
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Per-Agent Override
|
||||
|
||||
```yaml
|
||||
agents:
|
||||
defaults:
|
||||
memorySearch:
|
||||
provider: openai # Default for all agents
|
||||
|
||||
agents:
|
||||
research-bot:
|
||||
memorySearch:
|
||||
provider: cognee # Override for this agent
|
||||
cognee:
|
||||
searchType: GRAPH_COMPLETION
|
||||
maxResults: 10
|
||||
```
|
||||
|
||||
## Docker Production Tips
|
||||
|
||||
### Health Checks
|
||||
|
||||
Add health checks to docker-compose.yml:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
cognee:
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
start_period: 40s
|
||||
```
|
||||
|
||||
### Resource Limits
|
||||
|
||||
```yaml
|
||||
services:
|
||||
cognee:
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
cpus: '2'
|
||||
memory: 4G
|
||||
reservations:
|
||||
cpus: '1'
|
||||
memory: 2G
|
||||
```
|
||||
|
||||
### Persistent Storage
|
||||
|
||||
Mount volumes for persistence:
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
- ./cognee_data:/app/cognee/.cognee_system
|
||||
- ./cognee_logs:/app/logs
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [Cognee Documentation](https://docs.cognee.ai/)
|
||||
- [Cognee GitHub](https://github.com/topoteretes/cognee)
|
||||
- [Clawdbot Memory Guide](/memory)
|
||||
- [Docker Setup Guide](/install/docker)
|
||||
|
||||
## Feedback
|
||||
|
||||
Cognee integration is new. Report issues at:
|
||||
- Clawdbot: [github.com/clawdbot/clawdbot/issues](https://github.com/clawdbot/clawdbot/issues)
|
||||
- Cognee: [github.com/topoteretes/cognee/issues](https://github.com/topoteretes/cognee/issues)
|
||||
- Connection test: `curl http://localhost:8000/health`
|
||||
- Reset cached values that Moltbot reuses: `mv "$HOME/.clawdbot/memory/cognee/main.json" "$HOME/.clawdbot/memory/cognee/main.json.bak"`
|
||||
Reference in new issue
Block a user