knowledge-vault

name	knowledge-vault
description	Query the Knowledge Vault MCP server — search sources, indexed dev-notes, transcripts/artifacts, and ask questions over scoped vault content.
category	research

Knowledge Vault

Repo: /home/clawdbot/projects/knowledge-vault

Standalone read-only MCP server for the Agent Knowledge Vault. It exposes scoped PostgreSQL reads over knowledge_sources and knowledge_artifacts, including indexed /home/clawdbot/dev-notes markdown notes.

Scope defaults:

• workspace: jerry
• namespaces: jerry-private,hermes-private
• shared visibility included
• active sources/artifacts only

MCP tools

Tool	Description
vault_search	Search all sources by keyword, thinker, topic, or source type
vault_search_notes	Search indexed dev-notes by keyword, area, project, note type, or status
vault_thinkers	List thinkers/authors with counts and topics
vault_topics	List topics with counts
vault_get_source	Source metadata by source ID
vault_get_artifact	Full transcript/article/note body text by artifact ID
vault_get_transcript	Preferred source-ID → artifact-body lookup
vault_ask	Natural language question → synthesized answer from scoped vault content

Dev-notes indexing

cd /home/clawdbot/projects/knowledge-vault
uv run python scripts/index_dev_notes.py --dry-run
uv run python scripts/index_dev_notes.py

The indexer scans /home/clawdbot/dev-notes, excludes Archive/ by default, infers retrieval metadata from the new lanes (Areas, Projects, Resources, Learning, System), and writes stable dev-notes://... source URIs with full markdown artifacts.

Use vault_search_notes first for notes. It returns both source IDs and artifactId; call vault_get_artifact with artifactId for the full note.

Adding source material

Do not use ~/.hermes/archive as durable storage. For books, PDFs, articles, transcripts, or source bundles:

1. Stage local files only temporarily if extraction is needed.
2. Store source metadata and allowed/extracted text in Knowledge Vault/PostgreSQL.
3. Use canonical public URLs or stable knowledge-vault://source/<id> and knowledge-vault://artifact/<id>#full-text URIs.
4. Scrub local paths from active metadata.
5. Verify with vault_search, vault_get_source, and vault_get_transcript / vault_get_artifact.

Running

cd /home/clawdbot/projects/knowledge-vault
uv sync --extra dev
uv run python server.py

Requires DATABASE_URL, or an env file containing it. The server checks $HERMES_HOME/.env, ~/.hermes/.env, /home/clawdbot/.hermes/.env, ~/.hermes/hermes-agent/.env, and /home/clawdbot/projects/agent-memory/.env.

Hermes MCP config

Add to ~/.hermes/config.yaml:

mcp_servers:
  knowledge-vault:
    command: uv
    args:
      - run
      - --directory
      - /home/clawdbot/projects/knowledge-vault
      - python
      - server.py
    timeout: 120
    connect_timeout: 60

Restart Hermes after editing MCP config.

Verification

uv run python -m py_compile server.py vault/db.py vault/dev_notes.py scripts/index_dev_notes.py
uv run python -m pytest -q

Direct smoke:

uv run python - <<'PY'
import asyncio, json
import server

async def main():
    print([tool.name for tool in server.TOOLS])
    result = await server.dispatch_tool('vault_search_notes', {'keyword': 'finite fields', 'area': 'bitcoin', 'limit': 2})
    print(json.loads(result[0].text)[0]['notePath'])

asyncio.run(main())
PY

Examples

• "Search the vault for Lyn Alden on energy"
• "Search my dev-notes for finite fields"
• "Find active Agent Memory project notes"
• "Get the transcript/artifact for source ID abc-123"
• "List all thinkers in the vault"