feat: add workspace foundation and RAG design spec by teknium1 · Pull Request #1324 · NousResearch/hermes-agent

teknium1 · 2026-03-14T17:42:57Z

Summary

add a design spec for a local-first Hermes workspace knowledgebase and RAG system
add the workspace foundation: canonical workspace/knowledgebase config, directory bootstrapping, manifest generation, explicit workspace search/list/status support, and a new workspace tool
add the retrieval stack: chunk indexing, hybrid sparse+dense retrieval, optional reranking, structural chunking, and gated turn-scoped workspace context injection that preserves Hermes prompt caching
add a real local EmbeddingGemma execution path via optional SentenceTransformers/Torch runtime, with graceful fallback when the optional stack is not installed
add setup-wizard support so users can opt into the heavier local workspace RAG runtime during install or later with hermes setup workspace
add workspace roots management so users can extend RAG coverage to additional directories, with non-recursive indexing by default for added roots
polish docs, banner UX, and source citation guidance

What this PR does

introduces workspace and knowledgebase config sections
creates default workspace/ and knowledgebase/ directories under HERMES_HOME
adds agent/workspace.py for:
- path resolution
- manifest generation
- line-based workspace search
- structural chunking for markdown and code
- chunk indexing into a local SQLite knowledgebase
- hybrid retrieval using FTS5 + dense similarity
- optional second-stage reranking
- gated workspace context formatting for the current turn
- local SentenceTransformers-based EmbeddingGemma loading when optional deps are installed
- optional sqlite-vec loading for faster dense candidate lookup
- active root normalization for canonical workspace + additional roots
adds tools/workspace_tool.py and includes it in Hermes core toolsets
adds CLI entry points:
- hermes workspace status
- hermes workspace index
- hermes workspace list
- hermes workspace search
- hermes workspace retrieve
- hermes workspace roots list
- hermes workspace roots add <path> [--recursive]
- hermes workspace roots remove <path-or-label>
adds interactive slash command support via /workspace
wires turn-scoped workspace context into run_agent.py using the same cache-safe pattern as Honcho: retrieval is appended to the current-turn user message only, never to the cached system prompt
adds setup support:
- hermes setup workspace
- full first-install wizard now includes a Workspace Knowledgebase & Local RAG section
- returning-user setup menu now exposes the same section
- optional runtime installer for hermes-agent[workspace-rag]
adds optional dependency group:
- hermes-agent[workspace-rag]
improves citation guidance:
- workspace turn-context explicitly instructs inline citations as [Source: relative/path]
- system prompt adds matching workspace citation guidance when the workspace tool is available
adds simple workspace visibility in the CLI banner:
- Activated Workspace(s): workspace, notes, ...

UX notes

the canonical Hermes workspace remains active by default
additional roots extend retrieval coverage without requiring users to move files into ~/.hermes/workspace
added roots are non-recursive by default to avoid accidentally indexing huge directory trees
users must opt into recursion with --recursive

Retrieval implementation notes

retrieval is hybrid: sparse FTS5 + dense embeddings merged with RRF
dense embeddings prefer a true local EmbeddingGemma path through sentence-transformers when available
reranking is optional and supports:
- local cross-encoder models via sentence-transformers
- Cohere rerank API
- Voyage rerank API
- heuristic fallback if no reranker runtime is available
if the local runtime is missing or a provider fails, Hermes degrades gracefully instead of breaking retrieval
sqlite-vec is optional acceleration, not a hard requirement
chunking is now better than fixed windows for the important cases:
- markdown prefers heading boundaries
- code prefers symbol/function/class boundaries

Why this scope

This gets the workspace RAG system into a genuinely usable and installable state without violating Hermes' caching/message invariants:

stable canonical workspace contract
explicit inspectable tooling
local-first retrieval path
optional acceleration and reranking
install-time or later opt-in for heavier local deps
current-turn-only grounding with citation guidance
simple banner visibility and additional roots for broader coverage

Test plan

source /home/teknium/.hermes/hermes-agent/.venv/bin/activate && python -m pytest tests/ -n0 -q
source /home/teknium/.hermes/hermes-agent/.venv/bin/activate && python -m pytest tests/hermes_cli/test_setup_workspace_rag.py tests/hermes_cli/test_banner_workspace.py tests/hermes_cli/test_workspace_roots.py tests/agent/test_workspace.py tests/test_run_agent.py -n0 -q
source /home/teknium/.hermes/hermes-agent/.venv/bin/activate && TMP_HOME=$(mktemp -d) && export HERMES_HOME="$TMP_HOME" && python -m hermes_cli.main workspace roots list && mkdir -p "$TMP_HOME/notes/nested" && printf 'top level note\n' > "$TMP_HOME/notes/top.txt" && printf 'deep note\n' > "$TMP_HOME/notes/nested/deep.txt" && python -m hermes_cli.main workspace roots add "$TMP_HOME/notes" && python -m hermes_cli.main workspace index && python -m hermes_cli.main workspace search note && python -m hermes_cli.main workspace roots remove "$TMP_HOME/notes"

@teknium1

Port and modernize PR #1324 onto current main with full profile/HERMES_HOME awareness. New files: - agent/workspace.py: Core workspace engine — path resolution, manifest generation, structural chunking (markdown heading-aware, code symbol-aware), chunk indexing into SQLite, hybrid retrieval (FTS5 sparse + dense embeddings via RRF), optional reranking (local cross-encoder, Cohere, Voyage, heuristic fallback), workspace roots management, turn-scoped context injection - tools/workspace_tool.py: Model-facing workspace tool (status/index/list/search/retrieve) - hermes_cli/workspace.py: CLI subcommands and /workspace slash command handler Integration points: - config.py: workspace and knowledgebase sections in DEFAULT_CONFIG, workspace/ knowledgebase dirs in ensure_hermes_home(), config version bump to 13 - toolsets.py: workspace tool added to _HERMES_CORE_TOOLS - model_tools.py: workspace_tool added to _discover_tools() - commands.py: /workspace CommandDef with subcommands - cli.py: /workspace slash command dispatch - run_agent.py: turn-scoped workspace RAG context injection (cache-safe — appended to current-turn user message only, never touches system prompt) - hermes_cli/main.py: hermes workspace subcommand tree (status/index/list/search/retrieve/roots) - hermes_cli/banner.py: workspace roots visibility in welcome banner - pyproject.toml: workspace-rag optional dependency group Profile-aware: all paths use get_hermes_home() from hermes_constants, never hardcoded ~/.hermes. Each profile gets its own workspace/ and knowledgebase/ directories. Retrieval modes: off (default), gated (heuristic trigger), always. Embedding: local SentenceTransformers when installed, hash fallback otherwise. Dense search: sqlite-vec acceleration when installed, Python cosine fallback. Tests: 18 new workspace-specific tests, all passing. Original PR: #1324 by @teknium1

@teknium1

Port and modernize PR NousResearch#1324 onto current main with full profile/HERMES_HOME awareness. New files: - agent/workspace.py: Core workspace engine — path resolution, manifest generation, structural chunking (markdown heading-aware, code symbol-aware), chunk indexing into SQLite, hybrid retrieval (FTS5 sparse + dense embeddings via RRF), optional reranking (local cross-encoder, Cohere, Voyage, heuristic fallback), workspace roots management, turn-scoped context injection - tools/workspace_tool.py: Model-facing workspace tool (status/index/list/search/retrieve) - hermes_cli/workspace.py: CLI subcommands and /workspace slash command handler Integration points: - config.py: workspace and knowledgebase sections in DEFAULT_CONFIG, workspace/ knowledgebase dirs in ensure_hermes_home(), config version bump to 13 - toolsets.py: workspace tool added to _HERMES_CORE_TOOLS - model_tools.py: workspace_tool added to _discover_tools() - commands.py: /workspace CommandDef with subcommands - cli.py: /workspace slash command dispatch - run_agent.py: turn-scoped workspace RAG context injection (cache-safe — appended to current-turn user message only, never touches system prompt) - hermes_cli/main.py: hermes workspace subcommand tree (status/index/list/search/retrieve/roots) - hermes_cli/banner.py: workspace roots visibility in welcome banner - pyproject.toml: workspace-rag optional dependency group Profile-aware: all paths use get_hermes_home() from hermes_constants, never hardcoded ~/.hermes. Each profile gets its own workspace/ and knowledgebase/ directories. Retrieval modes: off (default), gated (heuristic trigger), always. Embedding: local SentenceTransformers when installed, hash fallback otherwise. Dense search: sqlite-vec acceleration when installed, Python cosine fallback. Tests: 18 new workspace-specific tests, all passing. Original PR: NousResearch#1324 by @teknium1

glenkusuma · 2026-04-13T17:03:50Z

this feature is the missing piece for creating a usable knowledge base with obsidian wiki (llm-wiki & obsidian build in skills) making the agent more powerful combine with memory for high signal to use the knowledge base within a workspace, a reusable skills for procedural and creating a living knowledge system 🎉✨

teknium1 · 2026-04-19T00:29:36Z

Closing during PR triage — not pursuing this approach.

@teknium1

Port and modernize PR NousResearch#1324 onto current main with full profile/HERMES_HOME awareness. New files: - agent/workspace.py: Core workspace engine — path resolution, manifest generation, structural chunking (markdown heading-aware, code symbol-aware), chunk indexing into SQLite, hybrid retrieval (FTS5 sparse + dense embeddings via RRF), optional reranking (local cross-encoder, Cohere, Voyage, heuristic fallback), workspace roots management, turn-scoped context injection - tools/workspace_tool.py: Model-facing workspace tool (status/index/list/search/retrieve) - hermes_cli/workspace.py: CLI subcommands and /workspace slash command handler Integration points: - config.py: workspace and knowledgebase sections in DEFAULT_CONFIG, workspace/ knowledgebase dirs in ensure_hermes_home(), config version bump to 13 - toolsets.py: workspace tool added to _HERMES_CORE_TOOLS - model_tools.py: workspace_tool added to _discover_tools() - commands.py: /workspace CommandDef with subcommands - cli.py: /workspace slash command dispatch - run_agent.py: turn-scoped workspace RAG context injection (cache-safe — appended to current-turn user message only, never touches system prompt) - hermes_cli/main.py: hermes workspace subcommand tree (status/index/list/search/retrieve/roots) - hermes_cli/banner.py: workspace roots visibility in welcome banner - pyproject.toml: workspace-rag optional dependency group Profile-aware: all paths use get_hermes_home() from hermes_constants, never hardcoded ~/.hermes. Each profile gets its own workspace/ and knowledgebase/ directories. Retrieval modes: off (default), gated (heuristic trigger), always. Embedding: local SentenceTransformers when installed, hash fallback otherwise. Dense search: sqlite-vec acceleration when installed, Python cosine fallback. Tests: 18 new workspace-specific tests, all passing. Original PR: NousResearch#1324 by @teknium1

teknium1 added 2 commits March 14, 2026 10:42

docs: add workspace knowledgebase RAG spec

9834e62

feat: add workspace foundation and search tooling

b883202

teknium1 changed the title ~~docs: add workspace knowledgebase RAG design spec~~ feat: add workspace foundation and RAG design spec Mar 14, 2026

teknium1 added 6 commits March 14, 2026 11:53

feat: add workspace retrieval and turn injection

0a3bc90

feat: add local embeddinggemma backend path

9177179

feat: finish workspace retrieval pipeline

a19f335

feat: add workspace setup flow and docs

bff6505

feat: show workspace status in cli banner

7ad1018

feat: add workspace roots management

b045e08

teknium1 mentioned this pull request Apr 6, 2026

feat: add workspace foundation and RAG retrieval system #5619

Closed

alt-glitch mentioned this pull request Apr 17, 2026

feat(workspace): FTS5 foundation + pluggable indexer + agent tools #11796

Closed

19 tasks

teknium1 closed this Apr 19, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add workspace foundation and RAG design spec#1324

feat: add workspace foundation and RAG design spec#1324
teknium1 wants to merge 8 commits into
mainfrom
hermes/hermes-cf8340fc

teknium1 commented Mar 14, 2026 •

edited

Loading

Uh oh!

glenkusuma commented Apr 13, 2026

Uh oh!

teknium1 commented Apr 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

teknium1 commented Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What this PR does

UX notes

Retrieval implementation notes

Why this scope

Test plan

Uh oh!

glenkusuma commented Apr 13, 2026

Uh oh!

teknium1 commented Apr 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

teknium1 commented Mar 14, 2026 •

edited

Loading