Registry / ai-ml / ralph-hero-knowledge-index

ralph-hero-knowledge-index

library0.1.49jsnpmunverified

Semantic search over a personal knowledge corpus using SQLite + sqlite-vec for local embeddings, exposing a stdio MCP server to Claude Code. Version 0.1.49. Indexes markdown roots (defaults to `../../thoughts`). Supports multi-root indexing, gitignore-style ignore patterns, layered configuration (CLI, env vars, config file), and hybrid search with two-tiered retrieval tools (`knowledge_search` and `knowledge_recall`). Ships TypeScript types and provides a reindex CLI. Differentiated by local-only, file-based vector search with no external API dependencies, configurable memory tiers (doc, raw, reflection, wiki), and role-based retrieval policies. Releases appear to be early-stage (pre-1.0) with active development.

ai-ml storage

npm install ralph-hero-knowledge-index

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · RALPH-HERO-KNOWLED

ralph-hero-knowledge-index

ai-mljavascriptv0.1.49

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

✓ import { createMcpServer } from 'ralph-knowledge'

✗ const ralph = require('ralph-knowledge')

Package is ESM-only; named exports include `createMcpServer`, `searchKnowledge`, `reindex`. No default export.

KnowledgeConfig

✓ import type { KnowledgeConfig } from 'ralph-knowledge'

✗ import { KnowledgeConfig } from 'ralph-knowledge'

Type import only — TypeScript will error at runtime if used as value. Available from v0.1.40+.

searchKnowledge

✓ import { searchKnowledge } from 'ralph-knowledge'

✗ import { knowledgeSearch } from 'ralph-knowledge'

Function name is `searchKnowledge`; `knowledgeSearch` does not exist (that is an MCP tool name).

Indexes markdown roots and starts an MCP server that Claude Code can connect to for semantic search.

import { reindex, createMcpServer } from 'ralph-knowledge' import type { KnowledgeConfig } from 'ralph-knowledge' const config: KnowledgeConfig = { roots: ['~/projects/my-thoughts', '~/notes'], ignorePatterns: ['**/drafts/**', '*.bak'], dbPath: '~/.ralph-hero/knowledge.db' } // Reindex all roots await reindex(config) // Start MCP server for Claude Code const server = await createMcpServer(config) server.listen() // Server exposes tools: knowledge_search, knowledge_recall

Debug

Known issues

breakingReindex overwrites the entire vector store — all existing embeddings are dropped and rebuilt from scratch.

fix

Use incremental indexing (not yet supported) or backup the SQLite file before reindexing.

affects: >=0.1.0

deprecatedThe `knowledge_search` tool's `rerank` parameter defaults to `true` in current versions but may change in a future release.

fix

Explicitly pass `rerank: true` or `rerank: false` in your tool call to avoid surprises.

affects: >=0.1.40

gotchaConfiguration precedence is complex: CLI flags override env vars override config file over defaults. If a path is provided via CLI but isn't a valid directory, the tool fails silently or errors.

fix

Always validate that paths exist before running reindex. Check logs for 'Using roots from' message to confirm source.

affects: >=0.1.30

gotchaTilde expansion (~) only works on Unix-like systems. On Windows, ~ is treated as a literal character.

fix

Use full absolute paths or environment variables like $HOME when running on Windows.

affects: >=0.1.0

gotchaThe `knowledge_recall` tool's role-based tier policy maps `researcher` to `raw`, `reflection`, `doc`; `planner` to `reflection`, `wiki`, `doc`. These are fixed and cannot be customized at runtime.

fix

Use `knowledge_search` with explicit `memory_tier` if you need a different tier combination.

affects: >=0.1.30

gotchaOnly `.md` files are indexed by default. Other file types are silently ignored.

fix

Currently no configuration to include non-markdown files. If needed, manually convert to markdown or wait for a future release.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'better-sqlite3'

Missing native SQLite binding; package.json lists it as a dependency but it requires native compilation.

fix

Run `npm install` to install native addons. If using a platform without prebuilt binaries, ensure build tools are available (e.g., `apt install build-essential` on Linux).

TypeError: Cannot read properties of undefined (reading 'search')

Attempting to call `searchKnowledge` or an MCP tool before the database has been initialized via `reindex`.

fix

Call `await reindex(config)` before any search operations. The database must exist and be populated.

Usage: reindex [paths...]

Running `npm run reindex` without arguments when no configuration file exists and no env var is set.

fix

Either pass paths as CLI arguments (e.g., `npm run reindex -- /my/thoughts`), set the `RALPH_KNOWLEDGE_DIRS` env var, or create `~/.ralph/knowledge.config.json` with a `roots` array.

error: invalid memory_tier 'foo'

Passing an unrecognized tier name to `knowledge_search`. Valid tiers: `doc`, `raw`, `reflection`, `wiki`, `any`.

fix

Use one of the valid tier names: `doc`, `raw`, `reflection`, `wiki`, or `any` (case-sensitive).

Upgrade

Version history

0.1.49latest on npm

Audit

Dependencies

better-sqlite3requiredSQLite integration for storing and querying embeddings and chunks

sqlite-vecrequiredVector extension for SQLite enabling local embedding search (cosine similarity, hybrid search)

@modelcontextprotocol/sdkrequiredMCP SDK for exposing tools via stdio to Claude Code

Agent activity

16 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/cdubiel08/ralph-hero ↗

packageralph-hero-knowledge-index ↗

homepagehttps://github.com/cdubiel08/ralph-hero#readme ↗