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.
Python ai-agentsai-memoryknowledge-graphknowledge-managementknowledge-representationreccomendation-system
Document recommend API and RecSys harness in README docs.
Cursor Agentb168cb766b45
diff --git a/README.md b/README.mdindex 893ecc0..2e17762 100644--- a/README.md+++ b/README.md@@ -220,7 +220,8 @@ Once your data is in, BrainAPI exposes purpose-built retrieval endpoints (REST,| ---------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- || `/retrieve/context` | `POST` | **Relevant information for a piece of text** — the matching graph triples plus historical context || `/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:**@@ -240,15 +241,23 @@ curl "http://localhost:8000/retrieve/entity/status?target=Emily" \# → { "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```-These three cover the most common needs, but there are more (`/retrieve/hops`, `/retrieve/entities/neighbors`, `/retrieve/text-chunks`, …). Full list → [REST API Reference](https://brainapi.lumen-labs.ai/docs/rest).+**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).---@@ -257,7 +266,7 @@ These three cover the most common needs, but there are more (`/retrieve/hops`, `Out of the box BrainAPI is a general-purpose understanding engine. **Plugins** let you reshape it into something far more specific — without forking the core. Because plugins can add routes, swap agent prompts, and register MCP tools, the same engine can become:- **A cheap semantic search engine** — extract entities once, then serve fast graph-backed search instead of paying for vector queries every time.-- **A recommendation system** — build on `/retrieve/entity/synergies` and custom routes to surface related products, content or collaborators.+- **A recommendation system** — use `/retrieve/recommend` (and `/retrieve/entity/synergies` for same-type siblings) or plugins like `features-rec` / `recsys-gnn`.- **A domain-specific extractor** — override the Scout/Architect prompts so the swarm understands your ontology (CRM, legal, medical, …).- **An agent toolset** — register custom MCP tools so any LLM runtime can read and write your brain.diff --git a/benchmarks/README.md b/benchmarks/README.mdindex 69ea41e..536302b 100644--- a/benchmarks/README.md+++ b/benchmarks/README.md@@ -6,6 +6,8 @@ Standalone HTTP-only harnesses (no `src/` imports):| --- | --- | --- || [LoCoMo](https://github.com/snap-research/LoCoMo) | `locomo/` | `./locomo.sh` || [LongMemEval](https://github.com/xiaowu0162/LongMemEval) | `longmemeval/` | `./longmemeval.sh` |+| [BEAM](https://github.com/mohammadtavakoli78/BEAM) | `beam/` | `./beam.sh` |+| RecSys (train-free `/retrieve/recommend`) | `recsys/` | `./recsys.sh` |Shared setup: `requirements.txt`, `.env` (`BRAINPAT_TOKEN`, LLM keys). Results ledger: [`REPORTS.json`](REPORTS.json). Agent notes: [`AGENTS.md`](AGENTS.md).@@ -219,11 +221,13 @@ Create a sibling package under `benchmarks/`:benchmarks/locomo/ # LoCoMo packagelongmemeval/ # LongMemEval package+ beam/ # BEAM package+ recsys/ # RecSys / recommend packageyourbench/ # new package with its own cli / client / metricsrequirements.txt # shared deps, or a per-bench requirements file```-Reuse patterns from `locomo/` / `longmemeval/`:+Reuse patterns from `locomo/` / `longmemeval/` / `recsys/`:- HTTP-only `BrainAPIClient`- JSONL resume files under `runs/`@@ -327,3 +331,34 @@ Do **not** ingest probing questions, rubrics, or ideal answers.**Cost warning:** even one 100K chat is ~100+ turns; start with `--limit-turns` / `--limit`.**1M wall time:** ~40h at concurrency 1; ~20–25h at 2 with healthy API (see `docs/research/10-beam-protocol.md`).++---++# RecSys benchmark for BrainAPI++Held-out next-item HitRate/Recall@K against **train-free** `GET /retrieve/recommend` (default) or optional plugin LightGCN. Uses structured ingest into brain `demorecsys` only — never LoCoMo/BEAM brains.++1. Optional MovieLens download (`ml-100k`) or toy JSONL fixtures under `data/`+2. Maps interactions → `POST /ingest/structured` (`mode=deterministic`)+3. Ranks with `GET /retrieve/recommend` (`--backend graph`) or LightGCN (`--backend lightgcn`)+4. Scores HitRate@K / Recall@K (+ diversity); upserts only `benchmarks.recsys`++Protocol: [`docs/research/16-recsys-eval-protocol.md`](../docs/research/16-recsys-eval-protocol.md).++## Quickstart++```bash+./recsys.sh smoke --backend graph+./recsys.sh download --name ml-100k+./recsys.sh evaluate --backend graph --dataset data/movielens_100k.jsonl --max-users 50+# attributed fixture (color/material):+./recsys.sh evaluate --backend graph --dataset data/recsys_toy_attrs.jsonl --min-interactions 2+# optional offline CF:+./recsys.sh evaluate --backend lightgcn --dataset data/recsys_toy.jsonl --epochs 20+```++### Scoring++- **Headline**: `hit_rate@K` / `recall@K` (K typically 10/20).+- Also: intra-list diversity, type coverage; report `model=graph-recommend` or `lightgcn`.+- Successful scored runs upsert `benchmarks.recsys` only — do not touch other suite keys.