shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

local-memory-rag

Build and query a private, offline, localhost-only Markdown knowledge index with keyword, fuzzy, or optional local semantic retrieval and relative-path citations. Use this Skill from Qoder, WorkBuddy, TRAE Work, or another productivity Agent when searching personal notes, meeting records, customer context, or another local Markdown vault without sending documents to an external service. Prefer this Skill over ad-hoc cloud RAG whenever the source material must remain on the device.

personAuthor: siuserhubgithub
open_in_newRepositorydownloadDownload package

Local Memory RAG

Keep source notes, index state, access token, queries, and results on the user's computer. Use the bundled standard-library Python runtime; do not install a cloud service or upload vault content.

Host interface

The fixed host entry point is scripts/run.ps1; macOS/Linux hosts use the equivalent scripts/run.sh. Hosts should call the entry point, not import internal Python modules. See references/host-integration.md.

Workflow

  1. Ask for or identify two directories:

    • vault: the existing Markdown knowledge directory.
    • state-root: a private directory outside the vault for configuration, token, and SQLite state.

  2. Configure once:

    ./scripts/run.sh configure --vault "/path/to/vault" --state-root "/path/to/private-state"

    For genuine paraphrase retrieval, point to an already-downloaded Sentence Transformers model and a local environment containing sentence-transformers:

    ./scripts/run.sh configure --vault "/path/to/vault" --state-root "/path/to/private-state" \
  --embedding-model "/path/to/local-model"

    Never download a model implicitly. If no model is configured, hybrid uses the bundled lexical/fuzzy fallback and reports retrieval_backend: lexical-fallback.

  3. Build or refresh the incremental index:

    ./scripts/run.sh index --state-root "/path/to/private-state"

  4. Pass private queries through standard input so they do not appear in process arguments:

    printf '%s\n' 'renewal decisions and unresolved risks' | \
  ./scripts/run.sh search --state-root "/path/to/private-state" --mode hybrid --limit 8

    On Windows PowerShell, replace ./scripts/run.sh with ./scripts/run.ps1 and pipe the query in the same way.

  5. Cite only the returned citation or relative_path. Never expose the absolute vault or state path in an answer.

Filters

Use --track, --status, --type, or --tag when the Markdown frontmatter contains those fields. Combine filters to narrow results.

Local HTTP mode

Start the authenticated service only on loopback:

./scripts/run.sh serve --state-root "/path/to/private-state" --host 127.0.0.1 --port 8765

The service exposes public GET /health and Bearer-protected POST /v1/search. Use client-search to avoid manually reading or printing the token:

printf '%s\n' 'customer decision' | \
  ./scripts/run.sh client-search --state-root "/path/to/private-state"

Safety rules

  • Keep state-root outside any synced or published repository.
  • Re-run index after notes change; removed notes are removed from the index.
  • Re-run index after changing the local embedding model.
  • Do not put a query on the command line.
  • Do not reveal access.token, absolute paths, or raw private passages unless the user explicitly requests the passage content.
  • Stop and report the error if configuration or index state is unavailable; do not silently switch to an external retrieval provider.

Read references/api.md only when integrating a different localhost client.