Skip to content

BrainAPI is a knowledge graph–powered AI memory layer that transforms unstructured data into structured knowledge, enabling intelligent search, recommendations, and contextual memory for AI agents and applications.

Merge branch 'main' into cursor/brainapi-docs-review-5e33

Christian6ee9576f7eee
diff --cc README.md
index 2e17762,0cec57b..23b5f73
--- a/README.md
+++ b/README.md
@@@ -218,10 -218,9 +218,10 @@@ Once your data is in, BrainAPI exposes
| Endpoint | Method | What you get |
| ---------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
- | `/retrieve/context` | `POST` | **Relevant information for a piece of text** — the matching graph triples plus historical context |
+ | `/retrieve/context` | `POST` | **Relevant information for a piece of text** — graph triples, passages, historical context, and optional provenance |
| `/retrieve/entity/status` | `GET` | **Existence check** for a specific entity — returns whether it exists, its node, relationships, and observations |
-| `/retrieve/entity/synergies` | `GET` | **Similar things** related to a given one — effectively a recommendation algorithm over the graph |
+| `/retrieve/entity/synergies` | `GET` | **Sibling entities** of the same type — shared event hubs + embedding similarity (`top_k`, `labels`, `polarity`) |
+| `/retrieve/recommend` | `GET`/`POST` | **Train-free recommendations** — synergies plus asymmetric walks, multi-interest, optional attribute prefs |
**Get context for a question:**
@@@ -241,23 -241,15 +242,25 @@@ curl "http://localhost:8000/retrieve/en
# → { "exists": true, "node": {...}, "relationships": [...], "observations": [...] }
```
-**Find synergies (recommendations):**
+**Find synergies (same-type siblings):**
```sh
-curl "http://localhost:8000/retrieve/entity/synergies?target=Neural%20Networks%20101" \
+curl "http://localhost:8000/retrieve/entity/synergies?target=Neural%20Networks%20101&top_k=20" \
-H "Authorization: Bearer $BRAINPAT_TOKEN"
-# → similar entities ranked by how strongly they connect to the target
+# → similar entities ranked by association_score
```
++
+**Rank recommendations (product / next-item style):**
+
+```sh
+curl "http://localhost:8000/retrieve/recommend?target=u01&top_k=20&labels=PRODUCT&exclude_seen=true" \
+ -H "Authorization: Bearer $BRAINPAT_TOKEN"
+# → ranked recommendations with channel provenance (synergy / asymmetric / multi_interest / …)
+```
+
- These cover the most common needs, but there are more (`/retrieve/hops`, `/retrieve/entities/neighbors`, `/retrieve/text-chunks`, …). Full list → [Docs v2](https://brainapi.lumen-labs.ai/docs/v2).
++
+ These three cover the most common needs, but there are more (`/retrieve/hops`, `/retrieve/entities/neighbors`, `/retrieve/text-chunks`, …). Start with [Context retrieval](https://brainapi.lumen-labs.ai/docs/v2/retrieval/context) and the [docs hub](https://brainapi.lumen-labs.ai/docs/v2).
---