Skip to content

Commit 6ec42e9

Browse files
ornerydorneryd
committed
chore(docs): adding agent skills and hot path query cookbook, updating user facing documentaiton to disambiguate the knowledge policy targeting for profiles and policies
1 parent f7a64c7 commit 6ec42e9

14 files changed

Lines changed: 2147 additions & 46 deletions

‎README.md‎

Lines changed: 23 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,12 @@ Open [http://localhost:7474](http://localhost:7474) for the admin UI. For NVIDIA
5454

5555
---
5656

57+
> **Writing queries?** Start with the [Hot-Path Cypher Cookbook](docs/performance/hot-path-query-cookbook.md) — proven query shapes that route through the executor's specialized fast paths.
58+
>
59+
> 🤖 **Building with Claude / agents?** The [`docs/skills/`](docs/skills/) directory contains agent-ready skill files for every Cypher surface: query shapes, decay/promotion policies, managed embeddings, vector & hybrid search, and RAG procedures. Drop them into `.claude/skills/` to make agents fluent in NornicDB.
60+
61+
---
62+
5763
> Note: Docker on macOS does not expose Metal acceleration. The Apple Silicon image still runs, but GPU acceleration on macOS requires a native install from the [releases page](https://github.com/orneryd/NornicDB/releases) or a local build.
5864
5965
## What NornicDB Is
@@ -265,6 +271,8 @@ RETURN n ORDER BY decayScore(n) DESC
265271
```
266272

267273
> 📖 Deep dive: [Knowledge-Layer Policies](docs/user-guides/knowledge-layer-policies.md), [Decay Profiles](docs/user-guides/decay-profiles.md), [Promotion Policies](docs/user-guides/promotion-policies.md), and [Ebbinghaus-Roynard Bootstrap](docs/user-guides/ebbinghaus-roynard-bootstrap.md).
274+
>
275+
> 🤖 **Agent skills:** [Knowledge Policies](docs/skills/knowledge-policies.skill.md) · [Decay Tuning](docs/skills/decay-tuning.skill.md) · [Promotion Policies](docs/skills/promotion-policies.skill.md)
268276
269277
### 🔗 Auto-Relationships
270278

@@ -280,6 +288,8 @@ NornicDB weaves connections automatically:
280288
Native semantic search with GPU acceleration and hybrid retrieval support.
281289

282290
> 📖 Deep dive: [Vector Search Guide](docs/user-guides/vector-search.md) and [Qdrant gRPC Endpoint](docs/user-guides/qdrant-grpc.md).
291+
>
292+
> 🤖 **Agent skills:** [Vector & Full-Text Search](docs/skills/vector-search.skill.md) · [Managed Embeddings](docs/skills/managed-embeddings.skill.md) · [RAG Procedures](docs/skills/rag-procedures.skill.md)
283293
284294
**Cypher (Neo4j-compatible):**
285295

@@ -466,17 +476,19 @@ Start with the docs hub for role/task navigation, then use the issue index for s
466476
- [Documentation Hub](docs/README.md)
467477
- [Issue Index](docs/ISSUES-INDEX.md)
468478
469-
| Guide | Description |
470-
| ----------------------------------------------------------------------------- | ------------------------------ |
471-
| [Getting Started](docs/getting-started/README.md) | Installation & quick start |
472-
| [Docker Image Quick Reference](docs/getting-started/image-quick-reference.md) | Full runtime image matrix |
473-
| [API Reference](docs/api-reference/README.md) | Cypher functions & procedures |
474-
| [User Guides](docs/user-guides/README.md) | Complete examples & patterns |
475-
| [Performance](docs/performance/README.md) | Benchmarks vs Neo4j |
476-
| [Neo4j Migration](docs/neo4j-migration/README.md) | Compatibility & feature parity |
477-
| [Architecture](docs/architecture/README.md) | System design & internals |
478-
| [Docker Guide](docker/README.md) | Build & deployment |
479-
| [Development](docs/development/README.md) | Contributing & development |
479+
| Guide | Description |
480+
| ----------------------------------------------------------------------------- | ----------------------------------------------- |
481+
| [Getting Started](docs/getting-started/README.md) | Installation & quick start |
482+
| [Docker Image Quick Reference](docs/getting-started/image-quick-reference.md) | Full runtime image matrix |
483+
| [Hot-Path Cypher Cookbook](docs/performance/hot-path-query-cookbook.md) | Proven query shapes for fast latency |
484+
| [Agent Skills](docs/skills/README.md) | Claude/agent skill files for the Cypher surface |
485+
| [API Reference](docs/api-reference/README.md) | Cypher functions & procedures |
486+
| [User Guides](docs/user-guides/README.md) | Complete examples & patterns |
487+
| [Performance](docs/performance/README.md) | Benchmarks vs Neo4j |
488+
| [Neo4j Migration](docs/neo4j-migration/README.md) | Compatibility & feature parity |
489+
| [Architecture](docs/architecture/README.md) | System design & internals |
490+
| [Docker Guide](docker/README.md) | Build & deployment |
491+
| [Development](docs/development/README.md) | Contributing & development |
480492
481493
Additional deep dives referenced above:
482494

‎docs/features/vector-embeddings.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,11 @@ ollama serve
3333
ollama pull mxbai-embed-large
3434

3535
# Configure NornicDB
36-
export NORNICDB_EMBEDDING_URL=http://localhost:11434
36+
export NORNICDB_EMBEDDING_ENABLED=true
37+
export NORNICDB_EMBEDDING_PROVIDER=ollama
38+
export NORNICDB_EMBEDDING_API_URL=http://localhost:11434
3739
export NORNICDB_EMBEDDING_MODEL=mxbai-embed-large
40+
export NORNICDB_EMBEDDING_DIMENSIONS=1024
3841
```
3942

4043
### OpenAI
@@ -49,10 +52,13 @@ export NORNICDB_EMBEDDING_MODEL=text-embedding-3-small
4952

5053
```bash
5154
export NORNICDB_EMBEDDING_PROVIDER=local
52-
export NORNICDB_EMBEDDING_MODEL_PATH=/models/mxbai-embed-large.gguf
53-
export NORNICDB_EMBEDDING_GPU_LAYERS=-1 # Auto-detect
55+
export NORNICDB_EMBEDDING_MODEL=mxbai-embed-large # filename stem under NORNICDB_MODELS_DIR
56+
export NORNICDB_MODELS_DIR=/models # directory containing the .gguf files
57+
export NORNICDB_EMBEDDING_GPU_LAYERS=-1 # auto-detect
5458
```
5559

60+
The local provider resolves the model file as `${NORNICDB_MODELS_DIR}/${NORNICDB_EMBEDDING_MODEL}.gguf`.
61+
5662
### Which properties are embedded
5763

5864
By default, the embedding worker builds text from **all node properties** and **node labels**. Managed embedding metadata is stored internally (`EmbedMeta`) to avoid property namespace pollution. You can limit this so that only specific properties are used, or exclude others.

‎docs/operations/configuration.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -736,8 +736,12 @@ export NORNICDB_SEARCH_MIN_SIMILARITY=0.5
736736
export NORNICDB_PERSIST_SEARCH_INDEXES=true # Save/load BM25 and vector indexes (requires data_dir)
737737
738738
# Embeddings
739-
export NORNICDB_EMBEDDINGS_PROVIDER=local
740-
export NORNICDB_EMBEDDINGS_MODEL=bge-m3
739+
export NORNICDB_EMBEDDING_ENABLED=true
740+
export NORNICDB_EMBEDDING_PROVIDER=local # local | ollama | openai
741+
export NORNICDB_EMBEDDING_MODEL=bge-m3
742+
export NORNICDB_EMBEDDING_DIMENSIONS=1024
743+
export NORNICDB_EMBEDDING_API_URL=http://localhost:11434
744+
export NORNICDB_MODELS_DIR=./models # used by provider=local
741745
```
742746

743747
## Qdrant gRPC Endpoint (Qdrant SDK Compatibility)

‎docs/skills/README.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# NornicDB Consumer Skills
2+
3+
This directory holds Claude Code-style skill files that teach an agent how to **use** NornicDB features through its Cypher API. They are consumer-facing — every example is a Cypher statement or `CALL` procedure a user can run, not a reference to repo-internal code.
4+
5+
The skills live alongside the user guides because they are user documentation: a structured, agent-friendly summary of the same surface that humans read in `docs/user-guides/`.
6+
7+
## Skills in this directory
8+
9+
| File | What it covers |
10+
|---|---|
11+
| [`cypher-queries.skill.md`](cypher-queries.skill.md) | Hot-path Cypher cookbook — point lookup, batch retrieval, pagination, search, traversal, batched UNWIND/MERGE writes, cleanup, multi-tenant isolation. Maps query shapes to executor fast paths. |
12+
| [`knowledge-policies.skill.md`](knowledge-policies.skill.md) | The full DDL surface for decay profiles, parameter bundles, promotion profiles, and promotion policies. Diagnostics via `nornicdb.knowledgepolicy.*`. |
13+
| [`decay-tuning.skill.md`](decay-tuning.skill.md) | Picking `halfLifeSeconds`, `function`, `scoreFloor`, `visibilityThreshold`, `scoreFrom`. Forgetting and Ebbinghaus-Roynard consolidation curves. |
14+
| [`promotion-policies.skill.md`](promotion-policies.skill.md) | Reinforcement and dampening with `ON ACCESS` mutations, `WHEN` predicates, and Kalman-smoothed behavioral signals. |
15+
| [`managed-embeddings.skill.md`](managed-embeddings.skill.md) | Server-side embeddings: `WITH EMBEDDING`, `db.index.vector.embed`, the `ChunkEmbeddings` storage model, provider config. |
16+
| [`vector-search.skill.md`](vector-search.skill.md) | Vector and full-text indexes — `CREATE/DROP VECTOR INDEX`, `CREATE/DROP FULLTEXT INDEX`, `db.index.vector.queryNodes`, `db.index.fulltext.queryNodes`. |
17+
| [`rag-procedures.skill.md`](rag-procedures.skill.md) | `db.retrieve`, `db.rretrieve`, `db.rerank`, `db.infer` — assembling end-to-end RAG pipelines as Cypher. |
18+
19+
## How to use them with Claude Code
20+
21+
Each file is a self-contained Markdown skill with a YAML frontmatter (`name`, `description`). Make Claude Code aware of them by either:
22+
23+
1. **Project skills:** symlink or copy the desired files into `.claude/skills/<name>/SKILL.md` at the project root. Claude Code auto-loads project skills.
24+
2. **User skills:** copy them into `~/.claude/skills/<name>/SKILL.md` to enable everywhere.
25+
3. **Direct reference:** read or `@`-mention the file from inside any conversation; the YAML frontmatter still tells Claude when each one is relevant.
26+
27+
The mental model in every skill is Neo4j Cypher with NornicDB extensions noted explicitly. Nothing here documents internal storage mechanics — those belong in `docs/architecture/`.
28+
29+
## See also
30+
31+
- [`docs/user-guides/`](../user-guides/) — long-form human documentation for the same features.
32+
- [`docs/features/`](../features/) — feature overviews and architecture references.
33+
- [`docs/operations/configuration.md`](../operations/configuration.md) — environment variable and YAML configuration reference.

0 commit comments

Comments
 (0)