knowledge

Documentation

Overview

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0

* card.go — the graph's Map Of Content (Obsidian MOC). A compact, deterministic * digest of the whole graph: how many nodes of each kind, and the hubs. This is * the ONLY graph artifact small and stable enough to inject per turn; detail is * pulled on demand via Neighborhood/Search.

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0

* Package knowledge is the in-core knowledge graph — the "Obsidian in the core" * substrate. It is a pure, dependency-free undirected weighted graph over typed * nodes (facts, topics, projects, skills, tags, the user). The CLI layer derives * one from the existing memory and skill stores on demand; nothing here knows * where the data came from, which keeps it trivially testable. * * Design discipline (the user's token/headroom constraint): the graph is a * retrieval index, not prompt payload. Per turn only a tiny IndexCard (a map of * content: node counts + hubs) is cheap enough to inject; the actual node * neighborhoods are pulled on demand, exactly like memory's index/recall split.

Index

• type Graph
  • func New() *Graph
  • func (g *Graph) AddEdge(a, b string, w float64)
  • func (g *Graph) AddNode(n Node) *Node
  • func (g *Graph) CountByKind() map[Kind]int
  • func (g *Graph) Degree(id string) int
  • func (g *Graph) Edges() int
  • func (g *Graph) Hubs(limit int) []*Node
  • func (g *Graph) IndexCard(maxHubs int) string
  • func (g *Graph) Len() int
  • func (g *Graph) Neighborhood(id string, hops, limit int) []*Node
  • func (g *Graph) Neighbors(id string) []Neighbor
  • func (g *Graph) Node(id string) (*Node, bool)
  • func (g *Graph) Nodes() []*Node
  • func (g *Graph) Search(keywords []string, limit int) []*Node
• type Kind
• type Neighbor
• type Node

Types

type Graph

type Graph struct {
	// contains filtered or unexported fields
}

Graph is an undirected weighted multigraph stored as an adjacency map.

func New

func New() *Graph

New returns an empty graph.

func (*Graph) AddEdge

func (g *Graph) AddEdge(a, b string, w float64)

AddEdge adds (or reinforces) an undirected edge. It is a no-op when either endpoint is missing or when a == b, so callers can wire edges optimistically without pre-checking existence. Repeated edges accumulate weight.

func (*Graph) AddNode

func (g *Graph) AddNode(n Node) *Node

AddNode upserts a node by ID. Re-adding an existing ID updates its display fields and keeps the larger Weight, never dropping edges. Empty IDs and titles are ignored. Returns the stored node.

func (*Graph) CountByKind

func (g *Graph) CountByKind() map[Kind]int

CountByKind tallies nodes per kind.

func (*Graph) Degree

func (g *Graph) Degree(id string) int

Degree is the number of distinct neighbors of id.

func (*Graph) Edges

func (g *Graph) Edges() int

Edges is the undirected edge count.

func (*Graph) Hubs

func (g *Graph) Hubs(limit int) []*Node

Hubs returns the most connected nodes (weighted degree, then intrinsic weight, then ID), capped at limit. Hubs are the backbone of the index card.

func (*Graph) IndexCard

func (g *Graph) IndexCard(maxHubs int) string

IndexCard renders the map of content: a one-line tally by kind plus up to maxHubs hub titles. Returns "" for an empty graph. The output is deterministic for a given graph, so it does not bust the prompt cache when unchanged.

func (*Graph) Len

func (g *Graph) Len() int

Len is the node count.

func (*Graph) Neighborhood

func (g *Graph) Neighborhood(id string, hops, limit int) []*Node

Neighborhood returns the nodes reachable within `hops` of id (a breadth-first local graph), excluding the seed, ordered by hop distance then edge weight, capped at limit. This is the on-demand "pull" — the local graph of a node.

func (*Graph) Neighbors

func (g *Graph) Neighbors(id string) []Neighbor

Neighbors returns the adjacent nodes ordered by edge weight (desc), then ID (asc) for stability.

func (*Graph) Node

func (g *Graph) Node(id string) (*Node, bool)

Node returns a node by ID.

func (*Graph) Nodes

func (g *Graph) Nodes() []*Node

Nodes returns every node sorted by ID, for deterministic iteration (e.g. the wikilink-resolution pass).

func (*Graph) Search

func (g *Graph) Search(keywords []string, limit int) []*Node

Search ranks nodes by how many of the keywords appear in their title or summary, breaking ties by intrinsic weight then ID. Only nodes with at least one match are returned, capped at limit.

type Kind

type Kind string

Kind classifies a node. Kinds are stable string constants so IDs and cards stay byte-deterministic (and therefore prompt-cache friendly).

const (
	KindFact    Kind = "fact"
	KindTopic   Kind = "topic"
	KindProject Kind = "project"
	KindSkill   Kind = "skill"
	KindProfile Kind = "profile"
	KindTag     Kind = "tag"
)

type Neighbor

type Neighbor struct {
	ID     string
	Weight float64
}

Neighbor is an adjacent node and the accumulated weight of the edge to it.

type Node

type Node struct {
	ID      string
	Kind    Kind
	Title   string
	Summary string
	Weight  float64
}

Node is one vertex. ID is unique and namespaced by kind (e.g. "topic:auth"). Weight is an intrinsic relevance prior (a fact's score, a topic's mentions) used to break ties in ranking; it is not the edge weight.