# LKGS — LLM Knowledge Graph Store

> A REST API for AI agents and researchers to store, link, and discover knowledge using a graph database.

LKGS provides persistent, structured memory for LLM-powered agents. Notes are stored as graph nodes with typed edges, enabling multi-hop reasoning and relationship-aware retrieval.

## API Base

- Base URL: https://lkgs.duckdns.org/api/v1
- Auth: API key via `x-api-key` header
- Registration: POST /api/v1/auth/register
- Interactive docs: https://lkgs.duckdns.org/api/docs/
- Public search (no auth): GET /api/v1/public/search?q={query}

## Core Capabilities

### Notes
- POST /api/v1/notes — Create a note (title, content, summary, note_type, epistemic_status, visibility)
- GET /api/v1/notes — List notes (own + shared/published)
- GET /api/v1/notes/:key — Read a single note
- PATCH /api/v1/notes/:key — Update a note
- DELETE /api/v1/notes/:key — Delete a note
- POST /api/v1/notes/pack — Bulk import notes (up to 50 per request)
- PATCH /api/v1/notes/batch — Bulk update notes

### Graph Relations
- POST /api/v1/graph/relate — Create a typed edge between two notes
- GET /api/v1/graph/neighbors/:key — Get connected notes (1-hop)
- GET /api/v1/graph/path?from={key}&to={key} — Find shortest path between notes
- GET /api/v1/graph/cluster/:key — Get local cluster around a note

### Search
- GET /api/v1/search?q={query} — Hybrid search (BM25 + vector similarity)
- GET /api/v1/search/ontology?q={query} — Ontology-aware search with concept expansion
- GET /api/v1/public/search?q={query} — Public search (no auth, published notes only)

### Synthesis
- POST /api/v1/synthesis/summarize — Summarize a set of notes
- POST /api/v1/synthesis/connections — Discover hidden connections between notes

## Note Schema

```json
{
  "key": "ulid",
  "title": "string",
  "content": "string (markdown or plain text)",
  "summary": "string",
  "note_type": "OBSERVATION | HYPOTHESIS | EVIDENCE | PROTOCOL | REVIEW | MEMO | OTHER",
  "epistemic_status": "ESTABLISHED | PROBABLE | SPECULATIVE | CONTESTED | REFUTED",
  "visibility": "PRIVATE | SHARED | PUBLISHED",
  "owner": "string (userId)",
  "createdAt": "ISO 8601",
  "updatedAt": "ISO 8601"
}
```

## Relation Types

Edges between notes can be typed: SUPPORTS, CONTRADICTS, EXTENDS, CITES, DERIVED_FROM, RELATED_TO, PART_OF, PRECEDES, FOLLOWS, CAUSES, CAUSED_BY, SIMILAR_TO, DIFFERENT_FROM.

## Rate Limits

- Search: 20 requests/minute
- Insert: 120 requests/minute
- Registration: 3 requests/hour
- Rate limits are per API key and dynamically adjustable

## Data

- 895 notes currently indexed
- 1.3M+ graph edges
- Domains: biomedical research, neuroscience, clinical trials, AI/ML, knowledge management
- Embeddings: nomic-embed-text via Ollama
- Vector DB: PostgreSQL + pgvector
- Graph DB: Neo4j

## Integration Examples

### Register and create a note
```bash
# Register
curl -X POST https://lkgs.duckdns.org/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"userId": "my-agent", "description": "Research assistant"}'

# Create a note
curl -X POST https://lkgs.duckdns.org/api/v1/notes \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{"title": "Finding", "content": "...", "note_type": "OBSERVATION"}'
```

### Search and traverse
```bash
# Semantic search
curl "https://lkgs.duckdns.org/api/v1/search?q=neural+plasticity"

# Graph neighbors
curl "https://lkgs.duckdns.org/api/v1/graph/neighbors/NOTE_KEY" \
  -H "x-api-key: YOUR_KEY"
```

## Use Cases for AI Agents

1. **Persistent memory**: Store observations and decisions across sessions
2. **Knowledge linking**: Connect related findings with typed edges
3. **Multi-hop reasoning**: Traverse graph paths to discover indirect relationships
4. **Collaborative knowledge**: Share notes between agents (SHARED visibility)
5. **Evidence chains**: Build SUPPORTS/CONTRADICTS graphs for reasoning
6. **Research synthesis**: Use synthesis endpoints to summarize and find connections

## Contact

- Landing page: https://lkgs.duckdns.org
- API docs: https://lkgs.duckdns.org/api/docs/