Velocity and graph analytics

Change velocity

Analyze the rate and distribution of changes across your knowledge base over a time period.

GET /api/kiwi/velocity

string

default:"30d"

Time window. Supports Nd (days), Nw (weeks), Nm (months).

integer

default:"20"

Max number of items in hot/cold spot lists.

string

Limit analysis to a subdirectory.

curl 'http://localhost:3333/api/kiwi/velocity?period=14d&limit=5'

{
  "period": "14d",
  "total_changes": 87,
  "hot_spots": [
    {"path": "concepts/auth.md", "changes": 12},
    {"path": "runbooks/deploy.md", "changes": 9}
  ],
  "cold_spots": [
    {"path": "concepts/legacy.md", "changes": 0, "days_since_update": 120}
  ],
  "bursts": [
    {"date": "2026-04-28", "changes": 23, "actor": "agent:importer"}
  ],
  "single_author_pages": 14
}

integer

Total commits in the period.

array

Most frequently changed pages.

array

Least recently changed pages.

array

Days with unusually high change counts.

integer

Pages with only one contributor.

Use velocity data to identify knowledge that’s churning (hot spots may need stabilization) and knowledge that’s stale (cold spots may need review).

Graph analytics

Structural analysis of the wiki-link graph using PageRank and connectivity metrics.

GET /api/kiwi/graph/analytics

integer

default:"20"

Number of top pages to return.

curl 'http://localhost:3333/api/kiwi/graph/analytics?limit=10'

{
  "total_nodes": 142,
  "total_edges": 387,
  "components": 3,
  "largest_component_size": 138,
  "orphans": ["concepts/legacy.md", "scratch/notes.md"],
  "top_pages": [
    {"path": "concepts/auth.md", "pagerank": 0.042, "in_degree": 18, "out_degree": 5},
    {"path": "concepts/users.md", "pagerank": 0.038, "in_degree": 15, "out_degree": 8}
  ]
}

integer

Total pages in the graph.

integer

Total wiki-link connections.

integer

Number of disconnected subgraphs.

integer

Pages in the largest connected component.

array

Pages with no incoming or outgoing links.

array

Highest PageRank pages with degree counts.

Returns 503 if the link indexer is not available.

Centrality, communities, path, and walk

Additional graph helpers live alongside /graph/analytics:

Endpoint	Purpose
`GET /graph/centrality?limit=50`	PageRank and betweenness-style rankings per page.
`GET /graph/communities`	Louvain community detection over wiki-link edges.
`GET /graph/path?from=a.md&to=b.md`	Shortest path between two pages.
`GET /graph/walk?path=a.md`	One-hop neighbors, backlinks, and optional same-directory siblings.

See Utilities for response notes and error codes.

Suggestions

Get semantically similar pages for a given page, useful for “related pages” features and discovering missing links.

GET /api/kiwi/suggestions

string

required

File path to find suggestions for.

integer

default:"5"

Max suggestions to return.

curl 'http://localhost:3333/api/kiwi/suggestions?path=concepts/auth.md&limit=3'

{
  "suggestions": [
    {"target": "concepts/api-keys.md", "similarity": 0.89, "snippet": "API key authentication..."},
    {"target": "concepts/sessions.md", "similarity": 0.84, "snippet": "Session management..."}
  ]
}

Already-linked pages are filtered out. Requires vector search to be enabled.

Embeddings

Retrieve the raw embedding vectors for a page’s chunks.

GET /api/kiwi/embeddings

string

required

File path to retrieve embeddings for.

curl 'http://localhost:3333/api/kiwi/embeddings?path=concepts/auth.md'

{
  "path": "concepts/auth.md",
  "dimensions": 768,
  "chunks": [
    {"chunk_idx": 0, "text": "# Authentication\n\nOAuth2...", "vector": [0.012, -0.034, ...]},
    {"chunk_idx": 1, "text": "## Refresh tokens\n\n...", "vector": [0.008, 0.021, ...]}
  ]
}

Returns 503 if vector search is not enabled.

Eligible tasks

Retrieve ranked actionable tasks inferred from frontmatter metadata — pages with status fields indicating they are available for work.

GET /api/kiwi/eligible

curl 'http://localhost:3333/api/kiwi/eligible?limit=10'

{
  "tasks": [
    {"path": "tasks/t-42.md", "title": "Fix auth timeout", "status": "open", "priority": "high"},
    {"path": "tasks/t-15.md", "title": "Update onboarding", "status": "open", "priority": "medium"}
  ]
}

Useful for agents that need to pick up the next available task. MCP: kiwi_eligible.

Search evaluation

Benchmark your search quality against expected results.

POST /api/kiwi/eval

curl -X POST 'http://localhost:3333/api/kiwi/eval' \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {"question": "how does authentication work", "expected_paths": ["concepts/auth.md"]},
      {"question": "deploy checklist", "expected_paths": ["runbooks/deploy.md"]}
    ]
  }'

{
  "fts": {"hit_rate": 1.0, "mrr": 0.75, "precision_at_5": 0.6},
  "semantic": {"hit_rate": 1.0, "mrr": 0.9, "precision_at_5": 0.8},
  "per_query": [
    {"question": "how does authentication work", "fts_rank": 2, "semantic_rank": 1}
  ]
}

number

Fraction of queries where the expected page appeared in top-5.

number

Mean Reciprocal Rank across all queries.

number

Average precision in the top-5 results.

REST API

CLI

Change velocity

Graph analytics

Centrality, communities, path, and walk

Suggestions

Embeddings

Eligible tasks

Search evaluation

​Change velocity

​Graph analytics

​Centrality, communities, path, and walk

​Suggestions

​Embeddings

​Eligible tasks

​Search evaluation

Change velocity

Graph analytics

Centrality, communities, path, and walk

Suggestions

Embeddings

Eligible tasks

Search evaluation