# J-brain

**Repository Path**: SuperCoderMan521/J-brain

## Basic Information

- **Project Name**: J-brain
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-20
- **Last Updated**: 2026-07-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Agent, wiki, memory

## README

# JBrain

> A Spring AI + MyBatis knowledge brain inspired by GBrain.<br>
> 基于 Spring AI 与 MyBatis 的知识大脑，参考 GBrain 核心流程实现。

[简体中文](#简体中文) · [English](#english) · [API Reference](#api-reference)

JBrain keeps Markdown as the canonical knowledge source and uses PostgreSQL, pgvector, full-text search, graph relations, facts, and timelines as derived projections. It provides REST APIs, a tool-dispatch surface, Markdown skills, GBrain command compatibility, and an embedded Web Workbench.

---

## 简体中文

### 项目定位

JBrain 是一个使用 Java 21、Spring Boot、Spring AI、MyBatis、PostgreSQL 与 pgvector 实现的知识记忆与检索系统。项目参考 GBrain 的源代码结构与核心行为，覆盖从 Markdown 写入到检索、推理、记忆维护和时间线分析的完整流程。

JBrain 不是简单的向量数据库封装。它坚持以下原则：

1. Markdown 页面是知识真相源。
2. 数据库是可重建的检索与关系投影。
3. 写入页面时同步完成分块、向量化、Facts、Aliases、Edges 与 Timeline 构建。
4. 检索同时使用全文、向量和关系召回，并通过 RRF 融合。
5. Think 先检索证据，再生成带引用的回答。
6. 未深度复刻的 GBrain 命令保留为 `cataloged`，不会伪装成已实现。

### 核心能力

- Markdown 页面写入、读取与版本记录
- Recursive、Semantic、LLM 与 Code Chunker
- Spring AI ChatModel 与 EmbeddingModel
- PostgreSQL FTS、pgvector、关系召回与 RRF
- Aliases、Typed Edges、Facts Fence 与 Timeline
- Recall、Forget、Consolidate 与 Dream
- Chronicle 日记、历史回看、Last Seen 与 Backfill
- 对话解析、内置 Pattern、LLM polish/fallback、Eval 与 Nightly Probe
- Code Def、Refs、Callers、Callees 与索引就绪状态
- Markdown Skills Resolver 与 Tool Dispatch
- GBrain `src/commands/` 命令目录兼容层
- 多 Brain 挂载、Source Grants 与多模态元数据
- Spring Boot 内置 Web Workbench，无需 Node.js 构建

### 快速启动

```powershell
cd jbrain
$env:OPENAI_API_KEY="sk-..."
docker compose up
```

启动后访问：

- Web Workbench：`http://localhost:8080/`
- Health：`http://localhost:8080/actuator/health`
- Tool Catalog：`http://localhost:8080/tools`

### 如何构建记忆

在界面中进入 **Knowledge → Write → Build memory**，或调用：

```bash
curl -X POST http://localhost:8080/api/pages \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "people/alice-example",
    "title": "Alice Example",
    "pageType": "person",
    "content": "# Alice Example\n\nAlice works on retrieval.\n\n## Facts\n\n- Alice prefers concise citations."
  }'
```

该接口会执行：规范化 Markdown → 页面版本 → Chunk → Embedding → Facts → Aliases → Typed Edges → Timeline。

### 与 GBrain 的关系

JBrain 保留 GBrain 的 Markdown-first、派生数据库、混合检索、Skills、Commands、Chronicle、Conversation Parser 与 Code Intelligence 思路，并将运行时改为 Spring Boot/Spring AI/MyBatis。

当前命令层会明确区分：

- `mapped`：已映射到 JBrain 深度实现，可以运行。
- `cataloged`：已登记 GBrain 命令，但尚未完成等价实现。

`/tools` 当前是工具目录与 JSON 调度接口，不等同于完整的 MCP 协议传输服务器。

---

## English

### Overview

JBrain is a Java 21 knowledge-memory and retrieval system built with Spring Boot, Spring AI, MyBatis, PostgreSQL, and pgvector. Its architecture follows GBrain's source-led model while exposing a deployment shape familiar to Spring teams.

The core contract is:

1. Markdown pages are the source of truth.
2. Database rows are rebuildable retrieval and relationship projections.
3. Page ingestion rebuilds chunks, embeddings, facts, aliases, typed edges, and timeline rows.
4. Search combines full-text, vector, and relational recall with Reciprocal Rank Fusion.
5. Think retrieves evidence before generating a cited answer.
6. Incomplete command parity remains visible as `cataloged`.

### Features

- Markdown ingest, lookup, and page versioning
- Recursive, semantic, LLM-guided, and code chunkers
- Spring AI chat and embedding integration
- PostgreSQL FTS, pgvector, relational recall, reranking, and RRF
- aliases, typed edges, facts fences, and timelines
- recall, forget, consolidate, and Dream synthesis
- Chronicle day, on-this-day, since, last-seen, extraction, and backfill
- conversation parsing, built-in patterns, optional LLM polish/fallback, eval, and nightly probe
- code definitions, references, callers, callees, and readiness envelopes
- Markdown skill registry, resolver, and runner
- GBrain `src/commands/` compatibility catalog
- multiple Brain mounts, Source grants, and media metadata
- embedded Web Workbench with no Node.js build step

### Quick start

```powershell
cd jbrain
$env:OPENAI_API_KEY="sk-..."
docker compose up
```

Open `http://localhost:8080/`. Health is available at `http://localhost:8080/actuator/health`.

### Build memory

Use **Knowledge → Write → Build memory** in the Workbench, or call `POST /api/pages`. Ingestion writes the canonical Markdown file and refreshes every derived projection needed for retrieval and memory operations.

### GBrain compatibility

JBrain ports GBrain concepts and source behavior into a Spring runtime. Command entries marked `mapped` can execute through JBrain services. Entries marked `cataloged` are deliberately visible but disabled until their deep behavior is ported.

The `/tools` endpoints provide a tool catalog and JSON dispatch surface; they are not yet a complete MCP transport implementation.

---

## API Reference

### Runtime stack

| Layer | Technology |
| --- | --- |
| Runtime | Java 21, Spring Boot 3.4 |
| AI | Spring AI 2.0, OpenAI-compatible provider |
| ORM | MyBatis 3 |
| Database | PostgreSQL 16, pgvector, Flyway |
| UI | Static HTML, CSS, native ES modules |
| Canonical storage | Markdown files |

### Knowledge lifecycle

```text
Markdown
  → page + page_version
  → chunking
  → embeddings
  → facts + aliases
  → typed graph edges
  → timeline / chronicle projections
  → FTS + vector + relational recall
  → RRF / reranker
  → cited Think answer
```

### Main endpoints

| Purpose | Method | Endpoint |
| --- | --- | --- |
| Build memory | `POST` | `/api/pages` |
| Read page | `GET` | `/api/pages?slug=...` |
| Hybrid search | `POST` | `/api/search` |
| Grounded answer | `POST` | `/api/think` |
| Recall facts | `GET` | `/api/recall` |
| Forget facts | `POST` | `/api/forget` |
| Consolidate | `POST` | `/api/maintenance/consolidate` |
| Dream | `POST` | `/api/dream` |
| Chronicle | `GET/POST` | `/api/chronicle/*` |
| Conversation parser | `GET/POST` | `/api/conversation/*` |
| Code intelligence | `GET` | `/api/code/*` |
| Skills | `GET/POST` | `/api/skills/*` |
| Commands | `GET/POST` | `/api/commands/*` |
| Tool dispatch | `GET/POST` | `/tools`, `/tools/call` |
| Brain mounts | `GET/POST` | `/api/brains`, `/api/brains/mount` |
| Source grants | `GET/POST` | `/api/grants` |

### Search modes

| Mode | Retrieval shape | Use case |
| --- | --- | --- |
| `conservative` | small result set, no expansion | lowest cost |
| `balanced` | FTS + vector + relational | default |
| `tokenmax` | wider recall and expansion | maximum evidence |

### Search example

```bash
curl -X POST http://localhost:8080/api/search \
  -H "Content-Type: application/json" \
  -d '{"query":"who works on retrieval","mode":"balanced","limit":10}'
```

### Think example

```bash
curl -X POST http://localhost:8080/api/think \
  -H "Content-Type: application/json" \
  -d '{"query":"What do we know about Alice?","mode":"balanced","limit":8}'
```

### Tool example

```bash
curl http://localhost:8080/tools

curl -X POST http://localhost:8080/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name":"search","arguments":{"query":"retrieval","limit":5}}'
```

### Environment variables

| Variable | Default / purpose |
| --- | --- |
| `OPENAI_API_KEY` | AI Provider credential |
| `SPRING_DATASOURCE_URL` | `jdbc:postgresql://localhost:5432/jbrain` |
| `SPRING_DATASOURCE_USERNAME` | `jbrain` |
| `SPRING_DATASOURCE_PASSWORD` | `jbrain` |
| `JBRAIN_DATA_DIR` | `./data/brain` |
| `JBRAIN_SKILLS_DIR` | `./skills` |
| `JBRAIN_COMMANDS_DIR` | `./commands` |
| `JBRAIN_SOURCE_ID` | `host` |
| `JBRAIN_SEARCH_MODE` | `balanced` |
| `JBRAIN_CHAT_MODEL` | `gpt-4.1-mini` |
| `JBRAIN_EMBED_MODEL` | `text-embedding-3-small` |

### Project layout

```text
jbrain/
├─ commands/                    GBrain command manifest
├─ skills/                      Markdown skills and resolver
├─ src/main/java/com/example/jbrain/
│  ├─ api/                      REST and tool dispatch
│  ├─ chunker/                  text and code chunking
│  ├─ chronicle/                temporal memory
│  ├─ conversation/             conversation parser
│  ├─ code/                     code intelligence
│  ├─ ingest/                   Markdown ingest
│  ├─ mapper/                   MyBatis data access
│  ├─ memory/                   facts, graph, Dream
│  ├─ retrieval/                search, RRF, eval
│  ├─ skills/                   skill registry and runner
│  └─ think/                    cited synthesis
└─ src/main/resources/
   ├─ db/migration/             Flyway schema
   └─ static/                   embedded Workbench
```

### Web Workbench

The Workbench contains 11 modules:

`Overview` · `Knowledge` · `Search` · `Think` · `Memory` · `Chronicle` · `Conversation` · `Code Intelligence` · `Skills` · `Commands & Tools` · `Settings`

Only route, Source ID, search mode, and optional principal are stored in `sessionStorage`. Knowledge payloads, JDBC URLs, and Provider secrets are not persisted in the browser.

### Current boundary

- PostgreSQL + pgvector is required for the complete runtime.
- Provider-dependent operations require a valid API key.
- The command catalog is broader than the deeply mapped command set.
- Code chunking and edge extraction preserve the GBrain data shape, but do not yet embed the original tree-sitter runtime.
- `/tools` is a REST tool-dispatch compatibility layer, not a full MCP transport implementation.

## License

Choose and add a project license before public distribution.