Skip to content

Commit ed6e612

Browse files
ZaynJarvisZaynJarvis
committed
docs: update install guide with natural language triggers and port changes
- Guide users to say 'remember this' and similar phrases - Keep keyword triggers in skill files for agent detection - Change default ports to 11933 (server) and 11944 (agfs) - Remove export OPENVIKING_CONFIG_DIR since default is ~/.openviking - Support OpenClaw, Claude Code, and other agents in skills section - Move Rust CLI build instructions to advanced doc - Fix data dir note to reference storage.workspace - Remove migration guide from advanced doc
1 parent 447535c commit ed6e612

2 files changed

Lines changed: 65 additions & 81 deletions

File tree

‎INSTALL.md‎

Lines changed: 48 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -34,12 +34,7 @@ This installs `openviking-server` as a standalone tool you can run anywhere.
3434
curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash
3535
```
3636

37-
Or install from source:
38-
```bash
39-
git clone https://github.com/volcengine/OpenViking.git
40-
cd OpenViking
41-
cargo install --path crates/ov_cli
42-
```
37+
See [INSTALL_ADVANCED.md](./INSTALL_ADVANCED.md) for building from source.
4338

4439
### 4. Configure and Start Server
4540

@@ -76,18 +71,17 @@ EOF
7671

7772
**Replace `your-api-key` with your actual API key.**
7873

79-
> 💡 **Note:** Data is stored in `./data` by default. You can change this by setting the `OPENVIKING_CONFIG_DIR` environment variable before starting the server.
74+
> 💡 **Note:** Data is stored in `~/.openviking/data` by default (set via `storage.workspace` in ov.conf). See [INSTALL_ADVANCED.md](./INSTALL_ADVANCED.md) to customize data location.
8075
8176
Start the server in background:
8277

8378
```bash
84-
export OPENVIKING_CONFIG_DIR=~/.openviking
8579
nohup openviking-server > ~/.openviking/server.log 2>&1 &
8680
```
8781

8882
Check it's running:
8983
```bash
90-
curl http://localhost:1933/health
84+
curl http://localhost:11933/health
9185
# Should return: {"status": "ok"}
9286
```
9387

@@ -96,7 +90,7 @@ curl http://localhost:1933/health
9690
```bash
9791
cat > ~/.openviking/ovcli.conf << 'EOF'
9892
{
99-
"url": "http://localhost:1933"
93+
"url": "http://localhost:11933"
10094
}
10195
EOF
10296
```
@@ -107,55 +101,67 @@ Skills enable agents to use OpenViking. Install them to your agent's skill direc
107101

108102
> 🤖 **For AI Agents reading this:** Ask your user if they want to install the OpenViking skills (adding-memory, adding-resource, searching-context). Proceed only if they confirm.
109103
104+
**For OpenClaw:**
110105
```bash
111106
mkdir -p ~/.openclaw/skills
112107

113-
# Copy skills from OpenViking examples
114-
cp -r /path/to/openviking/examples/skills/adding-memory ~/.openclaw/skills/
115-
cp -r /path/to/openviking/examples/skills/adding-resource ~/.openclaw/skills/
116-
cp -r /path/to/openviking/examples/skills/searching-context ~/.openclaw/skills/
108+
# Download skills
109+
for skill in adding-memory adding-resource searching-context; do
110+
mkdir -p "$HOME/.openclaw/skills/$skill"
111+
curl -o "$HOME/.openclaw/skills/$skill/SKILL.md" \
112+
"https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/skills/$skill/SKILL.md"
113+
done
117114
```
118115

119-
Or download directly:
116+
**For Claude Code:**
120117
```bash
121-
mkdir -p ~/.openclaw/skills/adding-memory
122-
curl -o ~/.openclaw/skills/adding-memory/SKILL.md \
123-
https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/skills/adding-memory/SKILL.md
118+
mkdir -p ~/.claude/skills
119+
120+
# Download skills
121+
for skill in adding-memory adding-resource searching-context; do
122+
mkdir -p "$HOME/.claude/skills/$skill"
123+
curl -o "$HOME/.claude/skills/$skill/SKILL.md" \
124+
"https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/skills/$skill/SKILL.md"
125+
done
126+
```
124127

125-
mkdir -p ~/.openclaw/skills/adding-resource
126-
curl -o ~/.openclaw/skills/adding-resource/SKILL.md \
127-
https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/skills/adding-resource/SKILL.md
128+
**For other agents:** Install to your agent's skill/tools directory.
128129

129-
mkdir -p ~/.openclaw/skills/searching-context
130-
curl -o ~/.openclaw/skills/searching-context/SKILL.md \
131-
https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/skills/searching-context/SKILL.md
130+
Or copy from a local clone:
131+
```bash
132+
# Set your agent's skill directory
133+
SKILL_DIR=~/.openclaw/skills # adjust for your agent
134+
135+
cp -r /path/to/openviking/examples/skills/adding-memory "$SKILL_DIR/"
136+
cp -r /path/to/openviking/examples/skills/adding-resource "$SKILL_DIR/"
137+
cp -r /path/to/openviking/examples/skills/searching-context "$SKILL_DIR/"
132138
```
133139

134140
---
135141

136-
## Using Skills
142+
## Using OpenViking Memory
137143

138-
Once installed, agents can use these keywords during chat:
144+
Once skills are installed, you can use natural language to trigger OpenViking actions:
139145

140-
| Keyword | Skill | What It Does |
141-
|---------|-------|--------------|
142-
| `ovm` | adding-memory | Extracts and stores insights from conversation |
143-
| `ovr` | adding-resource | Imports files/URLs into OpenViking |
144-
| `ovs` | searching-context | Searches stored memories and resources |
146+
### Storing Memories
147+
Say things like:
148+
- "**Remember this**" — after sharing something worth remembering
149+
- "**Save this to memory**" — to persist an insight or decision
150+
- "**Keep this in mind**" — to store context for future reference
145151

146-
**Example chat flow:**
147-
```
148-
User: I prefer using vim for coding
149-
User: ovm
150-
→ Agent extracts and stores: "User prefers vim for coding"
152+
### Adding Resources
153+
Say things like:
154+
- "**Add this to OpenViking**" — when sharing a URL or file
155+
- "**Import https://example.com/docs**" — to add external knowledge
156+
- "**Save this resource**" — to store documents for later retrieval
151157

152-
User: Please add https://example.com/docs
153-
User: ovr
154-
→ Agent imports and processes the URL
158+
### Searching Context
159+
Say things like:
160+
- "**Search my memory for...**" — to find previously stored information
161+
- "**What do I know about...**" — to query your OpenViking context
162+
- "**Find in OpenViking...**" — to search across memories and resources
155163

156-
User: ovs What's my editor preference?
157-
→ Agent searches and returns: "User prefers vim for coding"
158-
```
164+
The agent will automatically detect these intents and use the appropriate OpenViking skills.
159165

160166
---
161167

@@ -209,7 +215,6 @@ uv tool install openviking
209215
curl -fsSL .../install.sh | bash # ov CLI
210216

211217
# Start server (background)
212-
export OPENVIKING_CONFIG_DIR=~/.openviking
213218
nohup openviking-server > ~/.openviking/server.log 2>&1 &
214219

215220
# Stop server

‎INSTALL_ADVANCED.md‎

Lines changed: 17 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ For the quick start guide, see **[INSTALL.md](./INSTALL.md)**.
2727
{
2828
"server": {
2929
"host": "0.0.0.0",
30-
"port": 1933,
30+
"port": 11933,
3131
"api_key": null,
3232
"cors_origins": ["*"]
3333
},
@@ -44,7 +44,7 @@ For the quick start guide, see **[INSTALL.md](./INSTALL.md)**.
4444
}
4545
},
4646
"agfs": {
47-
"port": 1833,
47+
"port": 11944,
4848
"log_level": "warn",
4949
"backend": "local",
5050
"timeout": 10,
@@ -169,9 +169,10 @@ For the quick start guide, see **[INSTALL.md](./INSTALL.md)**.
169169
| Field | Type | Default | Description |
170170
|-------|------|---------|-------------|
171171
| `server.host` | string | `"0.0.0.0"` | Server bind address |
172-
| `server.port` | int | `1933` | Server port |
172+
| `server.port` | int | `11933` | Server port |
173173
| `server.api_key` | string | `null` | API key for authentication |
174174
| `storage.workspace` | string | `"./data"` | Main data directory |
175+
| `storage.agfs.port` | int | `11944` | AGFS server port |
175176
| `storage.vectordb.backend` | string | `"local"` | Vector DB backend: local, volcengine |
176177
| `storage.agfs.backend` | string | `"local"` | AGFS backend: local, s3 |
177178
| `embedding.dense.provider` | string | `"volcengine"` | Embedding provider |
@@ -334,7 +335,7 @@ source $HOME/.cargo/env
334335
uv tool install openviking
335336

336337
# Configure firewall (example for UFW)
337-
sudo ufw allow 1933/tcp
338+
sudo ufw allow 11933/tcp
338339

339340
# Setup systemd service (see below)
340341
```
@@ -378,7 +379,7 @@ sudo systemctl status openviking
378379
```bash
379380
docker run -d \
380381
--name openviking \
381-
-p 1933:1933 \
382+
-p 11933:11933 \
382383
-v $(pwd)/data:/data \
383384
-v $(pwd)/ov.conf:/app/ov.conf \
384385
-e OPENVIKING_CONFIG_FILE=/app/ov.conf \
@@ -394,7 +395,7 @@ services:
394395
openviking:
395396
image: volcengine/openviking:latest
396397
ports:
397-
- "1933:1933"
398+
- "11933:11933"
398399
volumes:
399400
- ./data:/data
400401
- ./ov.conf:/app/ov.conf
@@ -424,7 +425,7 @@ spec:
424425
- name: openviking
425426
image: volcengine/openviking:latest
426427
ports:
427-
- containerPort: 1933
428+
- containerPort: 11933
428429
env:
429430
- name: OPENVIKING_CONFIG_FILE
430431
value: /app/ov.conf
@@ -450,8 +451,8 @@ spec:
450451
selector:
451452
app: openviking
452453
ports:
453-
- port: 1933
454-
targetPort: 1933
454+
- port: 11933
455+
targetPort: 11933
455456
```
456457
457458
---
@@ -521,7 +522,7 @@ vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000
521522
{
522523
"server": {
523524
"host": "0.0.0.0",
524-
"port": 1933,
525+
"port": 11933,
525526
"api_key": "your-secure-api-key",
526527
"cors_origins": ["https://yourdomain.com"]
527528
}
@@ -532,7 +533,7 @@ vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000
532533

533534
```json
534535
{
535-
"url": "http://localhost:1933",
536+
"url": "http://localhost:11933",
536537
"api_key": "your-secure-api-key"
537538
}
538539
```
@@ -550,7 +551,7 @@ server {
550551
ssl_certificate_key /path/to/key.pem;
551552
552553
location / {
553-
proxy_pass http://localhost:1933;
554+
proxy_pass http://localhost:11933;
554555
proxy_http_version 1.1;
555556
proxy_set_header Host $host;
556557
proxy_set_header X-Real-IP $remote_addr;
@@ -609,16 +610,16 @@ For large deployments, adjust:
609610

610611
### Port Conflicts
611612

612-
If port 1933 is taken:
613+
If port 11933 is taken:
613614

614615
```json
615616
{
616617
"server": {
617-
"port": 8080
618+
"port": 11934
618619
},
619620
"storage": {
620621
"agfs": {
621-
"port": 8081
622+
"port": 11945
622623
}
623624
}
624625
}
@@ -630,7 +631,7 @@ If port 1933 is taken:
630631
2. Verify server binds to `0.0.0.0` (not `127.0.0.1`)
631632
3. Test with curl from remote machine:
632633
```bash
633-
curl http://server-ip:1933/health
634+
curl http://server-ip:11933/health
634635
```
635636

636637
---
@@ -664,25 +665,3 @@ If port 1933 is taken:
664665
"auto_generate_l1": false
665666
}
666667
```
667-
668-
---
669-
670-
## Migration Guides
671-
672-
### From Vector-only RAG
673-
674-
See migration guide in documentation.
675-
676-
### From Other Memory Systems
677-
678-
Use import scripts to migrate existing data:
679-
680-
```python
681-
import openviking as ov
682-
683-
client = ov.SyncOpenViking(path="./data")
684-
client.initialize()
685-
686-
# Import from existing source
687-
client.add_resource(path="/path/to/existing/data")
688-
```

0 commit comments

Comments
 (0)