holetron-lab/fleet-memory
1
0
Fork 0
Code Releases Packages Activity Actions

feat(skill): validate links, strip images, include openapi.json and changelog (#614)

Browse source 
* feat(skill): validate links, strip images, include openapi.json and changelog

- Add post-processing step to rewrite Docusaurus site-root paths (e.g.
  /developer/foo) to proper relative .md paths within the skill
- Strip markdown and HTML images from all generated files since assets
  are not bundled with the skill
- Copy hindsight-docs/static/openapi.json into references/openapi.json
  and map /api-reference links to it
- Include changelog.md from src/pages/ alongside faq and best-practices
- Add final validation step that fails the build if any link still
  points outside the skill directory

* ci: run generate-docs-skill in verify-generated-files job

* fix(skill): strip unresolvable site-root links instead of leaving them broken

* fix(skill): write file when images stripped but no links rewritten

* chore(skill): regenerate with fixed links, stripped images, changelog and openapi

* fix(skill): handle changelog as directory, add agno/hermes integrations, rebase on main
This commit is contained in:
Nicolò Boschi 2026-03-19 12:32:33 +01:00 committed by GitHub
parent fe12be47a0
commit a706905653
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
31 changed files with 10571 additions and 113 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
.github/workflows/test.yml vendored
View file

@ -1775,6 +1775,9 @@ jobs:
- name: Run generate-clients
run: ./scripts/generate-clients.sh
- name: Run generate-docs-skill
run: ./scripts/generate-docs-skill.sh
- name: Run lint
run: ./scripts/hooks/lint.sh
@ -1789,6 +1792,7 @@ jobs:
echo "Please run the following commands locally and commit the changes:"
echo " ./scripts/generate-openapi.sh"
echo " ./scripts/generate-clients.sh"
echo " ./scripts/generate-docs-skill.sh"
echo " ./scripts/hooks/lint.sh"
echo ""
git diff --stat

144
scripts/generate-docs-skill.sh
View file

@ -175,6 +175,47 @@ for page in best-practices faq; do
done
done
# Process changelog — may be a single file or a directory
if [ -f "$PAGES_DIR/changelog.md" ] || [ -f "$PAGES_DIR/changelog.mdx" ]; then
for ext in md mdx; do
src="$PAGES_DIR/changelog.$ext"
if [ -f "$src" ]; then
dest="$REFS_DIR/changelog.md"
mkdir -p "$(dirname "$dest")"
if [[ "$src" == *.mdx ]]; then
convert_mdx_to_md "$src" "$dest"
else
cp "$src" "$dest"
fi
print_info "Included page: changelog.$ext"
fi
done
elif [ -d "$PAGES_DIR/changelog" ]; then
find "$PAGES_DIR/changelog" -type f \( -name "*.md" -o -name "*.mdx" \) | while read -r file; do
rel="${file#$PAGES_DIR/}"
dest="$REFS_DIR/$rel"
if [[ "$file" == *.mdx ]]; then
dest="${dest%.mdx}.md"
fi
mkdir -p "$(dirname "$dest")"
if [[ "$file" == *.mdx ]]; then
convert_mdx_to_md "$file" "$dest"
else
cp "$file" "$dest"
fi
print_info "Included changelog: ${file#$PAGES_DIR/changelog/}"
done
fi
# Copy OpenAPI spec into the skill
OPENAPI_SRC="$ROOT_DIR/hindsight-docs/static/openapi.json"
if [ -f "$OPENAPI_SRC" ]; then
cp "$OPENAPI_SRC" "$REFS_DIR/openapi.json"
print_info "Included: openapi.json"
else
print_warn "openapi.json not found at $OPENAPI_SRC — skipping"
fi
# Generate SKILL.md
print_info "Generating SKILL.md..."
cat > "$SKILL_DIR/SKILL.md" <<'EOF'
@ -208,6 +249,8 @@ All documentation is in `references/` organized by category:
references/
├── best-practices.md # START HERE — missions, tags, formats, anti-patterns
├── faq.md # Common questions and decisions
├── changelog/ # Release history and version changes (index.md + integrations/)
├── openapi.json # Full OpenAPI spec — endpoint schemas, request/response models
├── developer/
│ ├── api/ # Core operations: retain, recall, reflect, memory banks
│ └── *.md # Architecture, configuration, deployment, performance
@ -302,6 +345,107 @@ print_info "✓ Generated skill at: $SKILL_DIR"
print_info "✓ Documentation files: $(find "$REFS_DIR" -type f | wc -l | tr -d ' ')"
print_info "✓ SKILL.md created with search guidance"
# Rewrite Docusaurus absolute paths (e.g. /developer/foo) to relative paths
print_info "Rewriting Docusaurus absolute paths to relative paths..."
python3 - "$REFS_DIR" <<'PYTHON'
import sys
import re
import os
from pathlib import Path
refs_dir = Path(sys.argv[1]).resolve()
link_pattern = re.compile(r'\[([^\]]*)\]\((/[^)]*)\)')
SPECIAL_MAPPINGS = {
'/api-reference': 'openapi.json',
}
def try_resolve(url_path, refs_dir):
"""Try to find the file in refs_dir for a Docusaurus absolute path like /developer/foo."""
if url_path in SPECIAL_MAPPINGS:
candidate = refs_dir / SPECIAL_MAPPINGS[url_path]
return candidate if candidate.exists() else None
doc_path = url_path.lstrip('/')
for candidate in [
refs_dir / (doc_path + '.md'),
refs_dir / doc_path / 'index.md',
refs_dir / doc_path,
]:
if candidate.exists():
return candidate
return None
image_pattern = re.compile(r'!\[[^\]]*\]\([^)]*\)')
html_img_pattern = re.compile(r'<img\b[^>]*/?>', re.IGNORECASE)
changed = 0
for md_file in refs_dir.rglob("*.md"):
original_content = md_file.read_text()
# Strip images (markdown and HTML)
content = image_pattern.sub('', original_content)
content = html_img_pattern.sub('', content)
def rewrite(match):
text = match.group(1)
url = match.group(2)
anchor = ''
if '#' in url:
url, frag = url.split('#', 1)
anchor = '#' + frag
if not url or url == '/':
return text # strip link, keep text
resolved = try_resolve(url, refs_dir)
if resolved is None:
return text # strip unresolvable link, keep text
rel = os.path.relpath(resolved, md_file.parent)
return f'[{text}]({rel}{anchor})'
new_content = link_pattern.sub(rewrite, content)
if new_content != original_content:
md_file.write_text(new_content)
changed += 1
print(f"[INFO] Rewrote Docusaurus links in {changed} file(s)")
PYTHON
# Validate: no links point outside the skill directory
print_info "Validating links in generated skill files..."
python3 - "$SKILL_DIR" <<'PYTHON'
import sys
import re
from pathlib import Path
skill_dir = Path(sys.argv[1]).resolve()
errors = []
# Find all markdown links: [text](url) — exclude images too
link_pattern = re.compile(r'\[([^\]]*)\]\(([^)]+)\)')
for md_file in skill_dir.rglob("*.md"):
content = md_file.read_text()
for match in link_pattern.finditer(content):
url = match.group(2).split("#")[0].strip() # strip anchors
if not url:
continue
# Absolute URLs and anchors-only are fine
if url.startswith(("http://", "https://", "mailto:", "ftp://")):
continue
# Resolve relative to the file's directory
resolved = (md_file.parent / url).resolve()
if not str(resolved).startswith(str(skill_dir)):
errors.append(f" {md_file.relative_to(skill_dir)}: '{url}' -> {resolved}")
if errors:
print("ERROR: The following links point outside the skill directory.")
print("All links must be absolute URLs or relative paths within the skill.")
for e in errors:
print(e)
sys.exit(1)
print(f"[INFO] Link validation passed ({skill_dir})")
PYTHON
echo ""
print_info "Usage:"
echo " - Agents can use Glob to find files: references/developer/api/*.md"

2
skills/hindsight-docs/SKILL.md
View file

@ -28,6 +28,8 @@ All documentation is in `references/` organized by category:
references/
├── best-practices.md # START HERE — missions, tags, formats, anti-patterns
├── faq.md # Common questions and decisions
├── changelog/ # Release history and version changes (index.md + integrations/)
├── openapi.json # Full OpenAPI spec — endpoint schemas, request/response models
├── developer/
│ ├── api/ # Core operations: retain, recall, reflect, memory banks
│ └── *.md # Architecture, configuration, deployment, performance

608
skills/hindsight-docs/references/changelog/index.md Normal file
View file

@ -0,0 +1,608 @@
---
hide_table_of_contents: true
---
# Changelog
This changelog highlights user-facing changes only. Internal maintenance, CI/CD, and infrastructure updates are omitted.
For full release details, see [GitHub Releases](https://github.com/vectorize-io/hindsight/releases).
## Integration Changelogs
| Integration | Package | Description |
|---|---|---|
| [LiteLLM](integrations/litellm.md) | `hindsight-litellm` | Universal LLM memory via LiteLLM (100+ providers) |
| [Pydantic AI](integrations/pydantic-ai.md) | `hindsight-pydantic-ai` | Persistent memory tools for Pydantic AI agents |
| [CrewAI](integrations/crewai.md) | `hindsight-crewai` | Persistent memory for CrewAI agents |
| [AI SDK](integrations/ai-sdk.md) | `@vectorize-io/hindsight-ai-sdk` | Memory integration for Vercel AI SDK |
| [Chat SDK](integrations/chat.md) | `@vectorize-io/hindsight-chat` | Memory integration for Vercel Chat SDK |
| [OpenClaw](integrations/openclaw.md) | `@vectorize-io/hindsight-openclaw` | Hindsight memory plugin for OpenClaw |
## [0.4.19](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.19)
**Features**
- TypeScript client now works in Deno environments. ([`72c25c97`](https://github.com/vectorize-io/hindsight/commit/72c25c97))
- Added Agno integration to use Hindsight as a memory toolkit. ([`8c378b98`](https://github.com/vectorize-io/hindsight/commit/8c378b98))
- Added Hermes Agent integration (hindsight-hermes) for persistent memory. ([`ef90842f`](https://github.com/vectorize-io/hindsight/commit/ef90842f))
- Expanded retain behavior with new `verbatim` and `chunks` extraction modes and named retain strategies. ([`e4f8a157`](https://github.com/vectorize-io/hindsight/commit/e4f8a157))
**Improvements**
- Improved local reranker performance/efficiency with FP16 and bucketed batching, plus compatibility with Transformers 5.x. ([`e7da7d0e`](https://github.com/vectorize-io/hindsight/commit/e7da7d0e))
**Bug Fixes**
- Prevented silent memory loss when consolidation fails (failed consolidations are tracked and can be recovered). ([`28dac7c7`](https://github.com/vectorize-io/hindsight/commit/28dac7c7))
- Fixed Docker control-plane startup to respect the configured control-plane hostname. ([`8a64dc8d`](https://github.com/vectorize-io/hindsight/commit/8a64dc8d))
- Database cleanup migration now removes orphaned observation memory units to avoid inconsistent memory state. ([`f09ad9de`](https://github.com/vectorize-io/hindsight/commit/f09ad9de))
- Deleting a document now also deletes linked memory units to prevent leftover/stale memory entries. ([`f27bd953`](https://github.com/vectorize-io/hindsight/commit/f27bd953))
- Fixed MCP middleware to send an Accept header, preventing 406 response errors in some setups. ([`836fd81e`](https://github.com/vectorize-io/hindsight/commit/836fd81e))
- Improved compatibility with Gemini tool-calling by preserving thought signature metadata to avoid failures on gemini-3.1-flash-lite-preview. ([`21f9f46c`](https://github.com/vectorize-io/hindsight/commit/21f9f46c))
## [0.4.18](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.18)
**Features**
- Add compound tag filtering using tag groups. ([`5de793ee`](https://github.com/vectorize-io/hindsight/commit/5de793ee))
- Publish new slim Python packages (hindsight-api-slim and hindsight-all-slim) for smaller installs. ([`15ea23d5`](https://github.com/vectorize-io/hindsight/commit/15ea23d5))
- Add MiniMax as a supported LLM provider. ([`2344484f`](https://github.com/vectorize-io/hindsight/commit/2344484f))
- Add Jina MLX reranker provider optimized for Apple Silicon. ([`1caf5ec9`](https://github.com/vectorize-io/hindsight/commit/1caf5ec9))
**Improvements**
- Allow configuring maximum recall query tokens via an environment variable. ([`66dedb8d`](https://github.com/vectorize-io/hindsight/commit/66dedb8d))
- Improve retrieval performance by switching to per-bank HNSW indexes. ([`43b3efc4`](https://github.com/vectorize-io/hindsight/commit/43b3efc4))
**Bug Fixes**
- Prevent reranking failures by truncating long documents that exceed LiteLLM reranker context limits. ([`eeb938fc`](https://github.com/vectorize-io/hindsight/commit/eeb938fc))
- Ensure recalled memories are injected as system context for OpenClaw. ([`b17f338e`](https://github.com/vectorize-io/hindsight/commit/b17f338e))
- Ensure embedded profiles are registered in CLI metadata when the daemon starts. ([`06b0f74a`](https://github.com/vectorize-io/hindsight/commit/06b0f74a))
- Cancel in-flight async operations when a bank is deleted to avoid dangling work. ([`0560f626`](https://github.com/vectorize-io/hindsight/commit/0560f626))
## [0.4.17](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.17)
**Features**
- Added a manual retry option for failed asynchronous operations. ([`dcaacbe4`](https://github.com/vectorize-io/hindsight/commit/dcaacbe4))
- You can now change/update tags on an existing document. ([`1b4ad7f4`](https://github.com/vectorize-io/hindsight/commit/1b4ad7f4))
- Added history tracking and a diff view for mental model changes. ([`e2baca8b`](https://github.com/vectorize-io/hindsight/commit/e2baca8b))
- Added observation history tracking with a UI diff view to review changes over time. ([`576473b6`](https://github.com/vectorize-io/hindsight/commit/576473b6))
- File uploads can now choose a parser per request, with configurable fallback chains. ([`99220d05`](https://github.com/vectorize-io/hindsight/commit/99220d05))
- Added an extension hook that runs after file-to-Markdown conversion completes. ([`1d17dea2`](https://github.com/vectorize-io/hindsight/commit/1d17dea2))
**Improvements**
- Operations view now supports filtering by operation type and has more reliable auto-refresh behavior. ([`f7a60f89`](https://github.com/vectorize-io/hindsight/commit/f7a60f89))
- Added token limits for “source facts” used during consolidation and recall to better control context usage. ([`5d05962d`](https://github.com/vectorize-io/hindsight/commit/5d05962d))
- Improved bank selector usability by truncating very long bank names in the dropdown. ([`1e40cd22`](https://github.com/vectorize-io/hindsight/commit/1e40cd22))
**Bug Fixes**
- Fixed webhook schema issues affecting multi-tenant retain webhooks. ([`32a4882a`](https://github.com/vectorize-io/hindsight/commit/32a4882a))
- Fixed file ingestion failures by stripping null bytes from parsed file content before retaining. ([`cd3a6a22`](https://github.com/vectorize-io/hindsight/commit/cd3a6a22))
- Fixed tool selection handling for OpenAI-compatible providers when using named tool_choice. ([`1cdfb7c2`](https://github.com/vectorize-io/hindsight/commit/1cdfb7c2))
- Improved consolidation behavior to prioritize a bank’s mission over an ephemeral-state heuristic. ([`00ccf0b2`](https://github.com/vectorize-io/hindsight/commit/00ccf0b2))
- Fixed database migrations to correctly handle mental model embedding dimension changes. ([`7accac94`](https://github.com/vectorize-io/hindsight/commit/7accac94))
- Fixed file upload failures caused by an Iris parser httpx read timeout. ([`fa3501d4`](https://github.com/vectorize-io/hindsight/commit/fa3501d4))
- Improved reliability of running migrations by serializing Alembic upgrades within the process. ([`f88b50a4`](https://github.com/vectorize-io/hindsight/commit/f88b50a4))
- Fixed Google Cloud Storage authentication when using Workload Identity Federation credentials. ([`d2504ac5`](https://github.com/vectorize-io/hindsight/commit/d2504ac5))
- Fixed the bank selector to refresh the bank list when the dropdown is opened. ([`0ad8c2d0`](https://github.com/vectorize-io/hindsight/commit/0ad8c2d0))
## [0.4.16](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.16)
**Features**
- Added Webhooks with `consolidation.completed` and `retain.completed` events. ([`abbf874d`](https://github.com/vectorize-io/hindsight/commit/abbf874d))
**Improvements**
- Improved OpenClaw recall/retention controls. ([`d425e93c`](https://github.com/vectorize-io/hindsight/commit/d425e93c))
- Improved search/reranking quality by switching combined scoring to multiplicative boosts. ([`aa8e5475`](https://github.com/vectorize-io/hindsight/commit/aa8e5475))
- Improved performance of observation recall by 40x on large banks. ([`ad2cf72a`](https://github.com/vectorize-io/hindsight/commit/ad2cf72a))
- Improved server shutdown behavior by capping graceful shutdown time and allowing a forced kill on a second Ctrl+C. ([`4c058b4b`](https://github.com/vectorize-io/hindsight/commit/4c058b4b))
**Bug Fixes**
- Fixed an async deadlock risk by running database schema migrations in a background thread during startup. ([`e0a2ac63`](https://github.com/vectorize-io/hindsight/commit/e0a2ac63))
- Fixed webhook delivery/outbox processing so transactions don’t silently roll back due to using the wrong database schema name. ([`75b95106`](https://github.com/vectorize-io/hindsight/commit/75b95106))
- Fixed observation results to correctly resolve and return related chunks using source_memory_ids. ([`cb6d1c46`](https://github.com/vectorize-io/hindsight/commit/cb6d1c46))
- Fixed MCP bank-level tool filtering compatibility with FastMCP 3.x. ([`f17406fd`](https://github.com/vectorize-io/hindsight/commit/f17406fd))
- Fixed crashes when an LLM returns invalid JSON across all retries (now handled cleanly instead of raising a TypeError). ([`66423b85`](https://github.com/vectorize-io/hindsight/commit/66423b85))
- Fixed observations without source dates to preserve missing (None) temporal fields instead of incorrectly populating them. ([`891c33b1`](https://github.com/vectorize-io/hindsight/commit/891c33b1))
## [0.4.15](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.15)
**Features**
- Added observation_scopes to control the granularity/visibility of observations. ([`55af4681`](https://github.com/vectorize-io/hindsight/commit/55af4681))
- List documents API now supports filtering by tags (and fixes the q parameter description). ([`1d70abfe`](https://github.com/vectorize-io/hindsight/commit/1d70abfe))
- Added PydanticAI integration for persistent agent memory. ([`cab5a40f`](https://github.com/vectorize-io/hindsight/commit/cab5a40f))
- Added richer entity label support (optional labels, free-form values, multi-value fields, and UI polish). ([`9b96becc`](https://github.com/vectorize-io/hindsight/commit/9b96becc))
- Added support for timestamp="unset" so content can be retained without a date. ([`f903948a`](https://github.com/vectorize-io/hindsight/commit/f903948a))
- OpenClaw can now automatically retain the last n+2 turns every n turns (default n=10). ([`ad1660b3`](https://github.com/vectorize-io/hindsight/commit/ad1660b3))
- Added configurable Gemini/Vertex AI safety settings for LLM calls. ([`73ef99e7`](https://github.com/vectorize-io/hindsight/commit/73ef99e7))
- Added extension hooks to customize root routing and error headers. ([`e407f4bc`](https://github.com/vectorize-io/hindsight/commit/e407f4bc))
**Improvements**
- Improved recall performance by fetching all recall chunks in a single query. ([`61bf428b`](https://github.com/vectorize-io/hindsight/commit/61bf428b))
- Improved recall/retain performance and scalability for large memory banks. ([`7942f181`](https://github.com/vectorize-io/hindsight/commit/7942f181))
**Bug Fixes**
- Fixed the TypeScript SDK to send null (not undefined) when includeEntities is false. ([`15f4b876`](https://github.com/vectorize-io/hindsight/commit/15f4b876))
- Prevented reflect from failing with context_length_exceeded on large memory banks. ([`77defd96`](https://github.com/vectorize-io/hindsight/commit/77defd96))
- Fixed a consolidation deadlock caused by retrying after zombie processing tasks. ([`c2876490`](https://github.com/vectorize-io/hindsight/commit/c2876490))
- Fixed observations count in the control plane that always showed 0. ([`eaeaa1f2`](https://github.com/vectorize-io/hindsight/commit/eaeaa1f2))
- Fixed ZeroEntropy rerank endpoint URL and ensured the MCP retain async_processing parameter is handled correctly. ([`f6f1a7d8`](https://github.com/vectorize-io/hindsight/commit/f6f1a7d8))
- Fixed JSON serialization issues and logging-related exception propagation when using the claude_code LLM provider. ([`ecb833f4`](https://github.com/vectorize-io/hindsight/commit/ecb833f4))
- Added bank-scoped request validation to prevent cross-bank/invalid bank operations. ([`5270aa5a`](https://github.com/vectorize-io/hindsight/commit/5270aa5a))
## [0.4.14](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.14)
**Features**
- Add Chat SDK integration to give chatbots persistent memory. ([`fed987f9`](https://github.com/vectorize-io/hindsight/commit/fed987f9))
- Allow configuring which MCP tools are exposed per memory bank, and expand the MCP tool set with additional tools and parameters. ([`3ffec650`](https://github.com/vectorize-io/hindsight/commit/3ffec650))
- Enable the bank configuration API by default. ([`4d030707`](https://github.com/vectorize-io/hindsight/commit/4d030707))
- Support filtering graph-based memory retrieval by tags. ([`0bb5ca4c`](https://github.com/vectorize-io/hindsight/commit/0bb5ca4c))
- Add batch observations consolidation to process multiple observations more efficiently. ([`0aa7c2b3`](https://github.com/vectorize-io/hindsight/commit/0aa7c2b3))
- Add OpenClaw options to toggle autoRecall and exclude specific providers. ([`3f9eb27c`](https://github.com/vectorize-io/hindsight/commit/3f9eb27c))
- Add a ZeroEntropy reranker provider option. ([`17259675`](https://github.com/vectorize-io/hindsight/commit/17259675))
**Improvements**
- Increase customization options for reflect, retain, and consolidation behavior. ([`2a322732`](https://github.com/vectorize-io/hindsight/commit/2a322732))
- Include source document metadata in fact extraction results. ([`87219b73`](https://github.com/vectorize-io/hindsight/commit/87219b73))
**Bug Fixes**
- Raise a clear error when embedding dimensions exceed pgvector HNSW limits (instead of failing later at runtime). ([`8cd65b98`](https://github.com/vectorize-io/hindsight/commit/8cd65b98))
- Fix multi-tenant schema isolation issues in storage and the bank config API. ([`b180b3ad`](https://github.com/vectorize-io/hindsight/commit/b180b3ad))
- Ensure LiteLLM embedding calls use the correct float encoding format to prevent embedding failures. ([`58f2de70`](https://github.com/vectorize-io/hindsight/commit/58f2de70))
- Improve recall performance by reducing memory usage during retrieval. ([`9f0c031d`](https://github.com/vectorize-io/hindsight/commit/9f0c031d))
- Handle observation regeneration correctly when underlying memories are deleted. ([`ac9a94ad`](https://github.com/vectorize-io/hindsight/commit/ac9a94ad))
- Fix reflect retrieval to correctly populate dependencies and enforce full hierarchical retrieval. ([`8b1a4658`](https://github.com/vectorize-io/hindsight/commit/8b1a4658))
- Fix OpenClaw health checks by passing the auth token to the health endpoint. ([`40b02645`](https://github.com/vectorize-io/hindsight/commit/40b02645))
## [0.4.13](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.13)
**Features**
- Switched the default OpenAI LLM to gpt-4o-mini. ([`325b5cc1`](https://github.com/vectorize-io/hindsight/commit/325b5cc1))
- Observation recall now includes the source facts behind recalled observations. ([`5569d4ad`](https://github.com/vectorize-io/hindsight/commit/5569d4ad))
- Added CrewAI integration to enable persistent memory. ([`41db2960`](https://github.com/vectorize-io/hindsight/commit/41db2960))
**Bug Fixes**
- Fixed npx hindsight-control-plane failing to run. ([`0758827d`](https://github.com/vectorize-io/hindsight/commit/0758827d))
- Improved MCP compatibility by aligning the local MCP implementation with the server and removing the deprecated stateless parameter. ([`ea8163c5`](https://github.com/vectorize-io/hindsight/commit/ea8163c5))
- Fixed Docker startup failures when using named Docker volumes. ([`ac739487`](https://github.com/vectorize-io/hindsight/commit/ac739487))
- Prevented reranker crashes when an upstream provider returns an error. ([`58c4d657`](https://github.com/vectorize-io/hindsight/commit/58c4d657))
- Improved accuracy of fact temporal ordering by reducing per-fact time offsets. ([`c3ef1555`](https://github.com/vectorize-io/hindsight/commit/c3ef1555))
- Client timeout settings are now properly respected. ([`dcaa9f14`](https://github.com/vectorize-io/hindsight/commit/dcaa9f14))
- Fixed documents not being tracked when fact extraction returns zero facts. ([`f78278ea`](https://github.com/vectorize-io/hindsight/commit/f78278ea))
## [0.4.12](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.12)
**Features**
- Accept and ingest PDFs, images, and common Office documents as inputs. ([`224b7b74`](https://github.com/vectorize-io/hindsight/commit/224b7b74))
- Add the Iris file parser for improved document parsing support. ([`7eafba66`](https://github.com/vectorize-io/hindsight/commit/7eafba66))
- Add async Retain support via provider Batch APIs (e.g., OpenAI and Groq) for higher-throughput ingestion. ([`40d42c58`](https://github.com/vectorize-io/hindsight/commit/40d42c58))
- Allow Recall to return chunks only (no memories) by setting max_tokens=0. ([`7dad9da0`](https://github.com/vectorize-io/hindsight/commit/7dad9da0))
- Add a Go client SDK for the Hindsight API. ([`2a47389f`](https://github.com/vectorize-io/hindsight/commit/2a47389f))
- Add support for the pgvectorscale (DiskANN) vector index backend. ([`95c42204`](https://github.com/vectorize-io/hindsight/commit/95c42204))
- Add support for Azure pg_diskann vector indexing. ([`476726c2`](https://github.com/vectorize-io/hindsight/commit/476726c2))
**Improvements**
- Improve reliability of async batch Retain when ingesting large payloads. ([`aefb3fcf`](https://github.com/vectorize-io/hindsight/commit/aefb3fcf))
- Improve AI SDK tooling to make it easier to work with Hindsight programmatically. ([`d06a0259`](https://github.com/vectorize-io/hindsight/commit/d06a0259))
**Bug Fixes**
- Ensure document tags are preserved when using the async Retain flow. ([`b4b5c44a`](https://github.com/vectorize-io/hindsight/commit/b4b5c44a))
- Fix OpenClaw ingestion failures for very large content (E2BIG). ([`6bad6673`](https://github.com/vectorize-io/hindsight/commit/6bad6673))
- Harden OpenClaw behavior (safer shell usage, better HTTP mode handling, and more reliable initialization), including per-user banks support. ([`c4610130`](https://github.com/vectorize-io/hindsight/commit/c4610130))
- Improve Python client async API consistency and reduce connection drop issues via keepalive timeout fixes. ([`8114ef44`](https://github.com/vectorize-io/hindsight/commit/8114ef44))
## [0.4.11](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.11)
**Features**
- Added support for LiteLLM SDK as an embeddings and reranking provider. ([`e408b7e`](https://github.com/vectorize-io/hindsight/commit/e408b7e))
- Expanded Postgres search support with additional text/vector extensions, including TimescaleDB pg_textsearch and vchord/pgvector options. ([`d871c30`](https://github.com/vectorize-io/hindsight/commit/d871c30))
- Added hierarchical configuration scopes (system, tenant, bank) for more flexible multi-tenant setup and overrides. ([`8d731f2`](https://github.com/vectorize-io/hindsight/commit/8d731f2))
- Added reverse proxy/base-path support for running Hindsight behind a proxy. ([`93ddd41`](https://github.com/vectorize-io/hindsight/commit/93ddd41))
- Added MCP tools to create, read, update, and delete mental models. ([`f641b30`](https://github.com/vectorize-io/hindsight/commit/f641b30))
- Added a "docs" skill for agents/tools to access documentation-oriented capabilities. ([`dd1e098`](https://github.com/vectorize-io/hindsight/commit/dd1e098))
- Added an OpenClaw configuration option to skip recall/retain for specific providers. ([`fb7be3e`](https://github.com/vectorize-io/hindsight/commit/fb7be3e))
**Improvements**
- Improved LiteLLM gateway model configuration for more reliable provider/model selection. ([`7d95a00`](https://github.com/vectorize-io/hindsight/commit/7d95a00))
- Exposed actual LLM token usage in retain results to improve cost/usage visibility. ([`83ca669`](https://github.com/vectorize-io/hindsight/commit/83ca669))
- Added user-initiated attribution to request context to improve async task and usage attribution. ([`90be7c6`](https://github.com/vectorize-io/hindsight/commit/90be7c6))
- Added OpenTelemetry tracing for improved request traceability and observability. ([`69dec8e`](https://github.com/vectorize-io/hindsight/commit/69dec8e))
- Helm chart: split TEI embedding and reranker into separate deployments for independent scaling and rollout. ([`43f9a8b`](https://github.com/vectorize-io/hindsight/commit/43f9a8b))
- Helm chart: added PodDisruptionBudgets and per-component affinity controls for more resilient scheduling. ([`9943957`](https://github.com/vectorize-io/hindsight/commit/9943957))
**Bug Fixes**
- Fixed a recursion issue in memory retention that could cause failures or runaway memory usage. ([`4f11210`](https://github.com/vectorize-io/hindsight/commit/4f11210))
- Fixed Reflect API serialization/schema issues for "based_on" so reflections are returned and stored correctly. ([`f9a8a8e`](https://github.com/vectorize-io/hindsight/commit/f9a8a8e))
- Improved MCP server compatibility by allowing extra tool arguments when appropriate and fixing bank ID resolution priority. ([`7ee229b`](https://github.com/vectorize-io/hindsight/commit/7ee229b))
- Added missing trust_code environment configuration support. ([`60574ee`](https://github.com/vectorize-io/hindsight/commit/60574ee))
- Hardened the MCP server with fixes to routing/validation and more accurate usage metering. ([`e798979`](https://github.com/vectorize-io/hindsight/commit/e798979))
- Fixed the slim Docker image to include tiktoken to prevent runtime tokenization errors. ([`6eec83b`](https://github.com/vectorize-io/hindsight/commit/6eec83b))
- Fixed MCP operations not being tracked correctly for usage metering. ([`888b50d`](https://github.com/vectorize-io/hindsight/commit/888b50d))
- Helm chart: fixed GKE deployments overriding the configured HINDSIGHT_API_PORT. ([`03f47e2`](https://github.com/vectorize-io/hindsight/commit/03f47e2))
## [0.4.10](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.10)
**Features**
- Provided a slimmer Docker distribution to reduce image size and speed up pulls. ([`f648178`](https://github.com/vectorize-io/hindsight/commit/f648178))
- Added Markdown support in Reflect and Mental Models content. ([`c4ef090`](https://github.com/vectorize-io/hindsight/commit/c4ef090))
- Added built-in Supabase tenant extension for running Hindsight with Supabase-backed multi-tenancy. ([`e99ee0f`](https://github.com/vectorize-io/hindsight/commit/e99ee0f))
- Added TenantExtension authentication support to the MCP endpoint. ([`fedfb49`](https://github.com/vectorize-io/hindsight/commit/fedfb49))
**Improvements**
- Improved MCP tool availability/routing based on the endpoint being used. ([`d90588b`](https://github.com/vectorize-io/hindsight/commit/d90588b))
**Bug Fixes**
- Stopped logging database usernames and passwords to prevent credential leaks in logs. ([`c568094`](https://github.com/vectorize-io/hindsight/commit/c568094))
- Fixed OpenClaw sessions wiping memory on each new session. ([`981cf60`](https://github.com/vectorize-io/hindsight/commit/981cf60))
- Fixed hindsight-embed profiles not loading correctly. ([`0430588`](https://github.com/vectorize-io/hindsight/commit/0430588))
- Fixed tagged directives so they correctly apply to tagged mental models. ([`278718d`](https://github.com/vectorize-io/hindsight/commit/278718d))
- Fixed a cast error that could cause failures at runtime. ([`093ecff`](https://github.com/vectorize-io/hindsight/commit/093ecff))
**Other**
- Added a docker-compose example to simplify local deployment and testing. ([`5179d5f`](https://github.com/vectorize-io/hindsight/commit/5179d5f))
## [0.4.9](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.9)
**Features**
- New AI SDK integration. ([`7e339e1`](https://github.com/vectorize-io/hindsight/commit/7e339e1))
- Add a Python SDK for running Hindsight in embedded mode (HindsightEmbedded). ([`d3302c9`](https://github.com/vectorize-io/hindsight/commit/d3302c9))
- Add streaming support to the hindsight-litellm wrappers. ([`665877b`](https://github.com/vectorize-io/hindsight/commit/665877b))
- Add OpenClaw support for connecting to an external Hindsight API and using dynamic per-channel memory banks. ([`6b34692`](https://github.com/vectorize-io/hindsight/commit/6b34692))
**Improvements**
- Improve the mental models experience in the control plane UI. ([`7097716`](https://github.com/vectorize-io/hindsight/commit/7097716))
- Reduce noisy Hugging Face logging output. ([`34d9188`](https://github.com/vectorize-io/hindsight/commit/34d9188))
**Bug Fixes**
- Improve recall endpoint reliability by handling timeouts correctly and rejecting overly long queries. ([`dd621a6`](https://github.com/vectorize-io/hindsight/commit/dd621a6))
- Improve /reflect behavior with Claude Code and Codex providers. ([`a43d208`](https://github.com/vectorize-io/hindsight/commit/a43d208))
- Fix OpenClaw shell argument escaping for more reliable command execution. ([`63e2964`](https://github.com/vectorize-io/hindsight/commit/63e2964))
## [0.4.8](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.8)
**Features**
- Added profile support for `hindsight-embed`, enabling separate embedding configurations/workspaces. ([`6c7f057`](https://github.com/vectorize-io/hindsight/commit/6c7f057))
- Added support for additional LLM backends, including OpenAI Codex and Claude Code. ([`539190b`](https://github.com/vectorize-io/hindsight/commit/539190b))
**Improvements**
- Enhanced OpenClaw and `hindsight-embed` parameter/config options for easier configuration and better defaults. ([`749478d`](https://github.com/vectorize-io/hindsight/commit/749478d))
- Added OpenClaw plugin configuration options to select LLM provider and model. ([`8564135`](https://github.com/vectorize-io/hindsight/commit/8564135))
- Server now prints its version during startup to simplify debugging and support requests. ([`1499ce5`](https://github.com/vectorize-io/hindsight/commit/1499ce5))
- Improved tracing/debuggability by propagating request context through asynchronous background tasks. ([`44d9125`](https://github.com/vectorize-io/hindsight/commit/44d9125))
- Added stronger validation and context for mental model create/refresh operations to prevent invalid requests. ([`35127d5`](https://github.com/vectorize-io/hindsight/commit/35127d5))
**Bug Fixes**
- Improved embedding CLI experience with richer logs and isolated profiles to avoid cross-contamination between runs. ([`794a743`](https://github.com/vectorize-io/hindsight/commit/794a743))
- Operation validation now runs correctly in the worker process, preventing invalid background operations from slipping through. ([`96f0e54`](https://github.com/vectorize-io/hindsight/commit/96f0e54))
- Fixed unreliable behavior when using a custom PostgreSQL schema. ([`3825506`](https://github.com/vectorize-io/hindsight/commit/3825506))
## [0.4.7](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.7)
**Features**
- Add extension hooks to validate and customize mental model operations. ([`9c3fda7`](https://github.com/vectorize-io/hindsight/commit/9c3fda7))
- Add support for using an external embedding API provider in OpenClaw plugin (with additional OpenClaw compatibility fixes). ([`4b57b82`](https://github.com/vectorize-io/hindsight/commit/4b57b82))
**Improvements**
- Speed up container startup by preloading the tiktoken encoding during Docker image builds. ([`039944c`](https://github.com/vectorize-io/hindsight/commit/039944c))
**Bug Fixes**
- Prevent PostgreSQL insert failures by stripping null bytes from text fields before saving. ([`ef9d3a1`](https://github.com/vectorize-io/hindsight/commit/ef9d3a1))
- Fix worker schema selection so it uses the correct default database schema. ([`d788a55`](https://github.com/vectorize-io/hindsight/commit/d788a55))
- Honor an already-set HINDSIGHT_API_DATABASE_URL instead of overwriting it in the hindsight-embed workflow. ([`f0cb192`](https://github.com/vectorize-io/hindsight/commit/f0cb192))
## [0.4.6](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.6)
**Improvements**
- Improved OpenClaw configuration setup to make embedding integration easier to configure. ([`27498f9`](https://github.com/vectorize-io/hindsight/commit/27498f9))
**Bug Fixes**
- Fixed OpenClaw embedding version binding/versioning to prevent mismatches when using the embed integration. ([`1163b1f`](https://github.com/vectorize-io/hindsight/commit/1163b1f))
## [0.4.5](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.5)
**Bug Fixes**
- Fixed occasional failures when retaining memories asynchronously with timestamps. ([`cbb8fc6`](https://github.com/vectorize-io/hindsight/commit/cbb8fc6))
## [0.4.4](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.4)
**Bug Fixes**
- Fixed async “retain” operations failing when a timestamp is provided. ([`35f0984`](https://github.com/vectorize-io/hindsight/commit/35f0984))
- Corrected the OpenClaw daemon integration name to “openclaw” (previously “openclawd”). ([`b364bc3`](https://github.com/vectorize-io/hindsight/commit/b364bc3))
## [0.4.3](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.3)
**Features**
- Add Vertex AI as a supported LLM provider. ([`c2ac7d0`](https://github.com/vectorize-io/hindsight/commit/c2ac7d0), [`49ae55a`](https://github.com/vectorize-io/hindsight/commit/49ae55a))
- Add Bearer token authentication for MCP and propagate tenant authentication across MCP requests. ([`0da77ce`](https://github.com/vectorize-io/hindsight/commit/0da77ce))
**Improvements**
- CLI: add a --wait flag for consolidate and a --date filter for listing documents. ([`ff20bf9`](https://github.com/vectorize-io/hindsight/commit/ff20bf9))
**Bug Fixes**
- Fix worker polling deadlocks to prevent background processing from stalling. ([`f4f86e3`](https://github.com/vectorize-io/hindsight/commit/f4f86e3))
- Improve reliability of Docker builds by retrying ML model downloads. ([`ecc590c`](https://github.com/vectorize-io/hindsight/commit/ecc590c))
- Fix tenant authentication handling for internal background tasks and ensure the control-plane forwards required auth to the dataplane. ([`03bf13e`](https://github.com/vectorize-io/hindsight/commit/03bf13e))
- Ensure tenant database migrations run at startup and workers use the correct tenant schema context. ([`657fe02`](https://github.com/vectorize-io/hindsight/commit/657fe02))
- Fix control-plane graph endpoint errors when upstream data is missing. ([`751f99a`](https://github.com/vectorize-io/hindsight/commit/751f99a))
**Other**
- Rename the default bot/user identity from "moltbot" to "openclaw". ([`728ce13`](https://github.com/vectorize-io/hindsight/commit/728ce13))
## [0.4.2](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.2)
**Features**
- Added Clawdbot/Moltbot/OpenClaw integration. ([`12e9a3d`](https://github.com/vectorize-io/hindsight/commit/12e9a3d))
**Improvements**
- Added additional configuration options to control LLM retry behavior. ([`3f211f0`](https://github.com/vectorize-io/hindsight/commit/3f211f0))
- Added real-time logs showing a detailed timing breakdown during consolidation runs. ([`8781c9f`](https://github.com/vectorize-io/hindsight/commit/8781c9f))
**Bug Fixes**
- Fixed hindsight-embed crashing on macOS. ([`c16ccc2`](https://github.com/vectorize-io/hindsight/commit/c16ccc2))
## [0.4.1](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.1)
**Features**
- Added support for using a non-default PostgreSQL schema by default. ([`2b72e1f`](https://github.com/vectorize-io/hindsight/commit/2b72e1f))
**Improvements**
- Improved memory consolidation performance (benchmarking and optimizations). ([`b43ef98`](https://github.com/vectorize-io/hindsight/commit/b43ef98))
**Bug Fixes**
- Fixed the /version endpoint returning an incorrect version. ([`cfcc23c`](https://github.com/vectorize-io/hindsight/commit/cfcc23c))
- Fixed mental model search failing due to UUID type mismatch after text-ID migration. ([`94cc0a1`](https://github.com/vectorize-io/hindsight/commit/94cc0a1))
- Added safer PyTorch device detection to prevent crashes on some environments. ([`67c4788`](https://github.com/vectorize-io/hindsight/commit/67c4788))
- Fixed Python packages exposing an incorrect __version__ value. ([`fccbdfe`](https://github.com/vectorize-io/hindsight/commit/fccbdfe))
## [0.4.0](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.0)
**Observations**, **Mental Models**, new **Agentic Reflect** and Directives, read the announcement.
**Features**
- Added support for providing a custom prompt for memory extraction. ([`3172e99`](https://github.com/vectorize-io/hindsight/commit/3172e99))
- Expanded the LiteLLM integration with async retain/reflect support, cleaner API, and support for tags/mission (including passing API keys correctly). ([`1d4879a`](https://github.com/vectorize-io/hindsight/commit/1d4879a))
- Added a new worker service to run background tasks at scale. ([`4c79240`](https://github.com/vectorize-io/hindsight/commit/4c79240))
- MCP retain now supports timestamps. ([`b378f68`](https://github.com/vectorize-io/hindsight/commit/b378f68))
- Added support for installing skills via `npx add-skill`. ([`ec22317`](https://github.com/vectorize-io/hindsight/commit/ec22317))
**Improvements**
- CLI retain-files now accepts more file types. ([`1eeced3`](https://github.com/vectorize-io/hindsight/commit/1eeced3))
**Bug Fixes**
- Fixed a macOS crash in the embed daemon caused by an XPC connection issue. ([`e5fc6ee`](https://github.com/vectorize-io/hindsight/commit/e5fc6ee))
- Fixed occasional extraction in the wrong language. ([`87d4a36`](https://github.com/vectorize-io/hindsight/commit/87d4a36))
- Fixed PyTorch model initialization issues that could cause startup failures (meta tensor/init problems). ([`ddaa5f5`](https://github.com/vectorize-io/hindsight/commit/ddaa5f5))
**Features**
- Add memory tags so you can label and filter memories during recall/reflect. ([`20c8f8b`](https://github.com/vectorize-io/hindsight/commit/20c8f8b))
- Allow choosing different AI providers/models per operation. ([`e6709d5`](https://github.com/vectorize-io/hindsight/commit/e6709d5))
- Add Cohere support for embeddings and reranking. ([`4de0730`](https://github.com/vectorize-io/hindsight/commit/4de0730))
- Add configurable embedding dimensions and OpenAI embeddings support. ([`70de23e`](https://github.com/vectorize-io/hindsight/commit/70de23e))
- Support custom base URLs for OpenAI-style embeddings and Cohere endpoints. ([`fa53917`](https://github.com/vectorize-io/hindsight/commit/fa53917))
- Add LiteLLM gateway support for routing LLM/embedding requests. ([`d47c8a2`](https://github.com/vectorize-io/hindsight/commit/d47c8a2))
- Add multilingual content support to improve handling and retrieval across languages. ([`c65c6a9`](https://github.com/vectorize-io/hindsight/commit/c65c6a9))
- Add delete memory bank capability. ([`4b82d2d`](https://github.com/vectorize-io/hindsight/commit/4b82d2d))
- Add backup/restore tooling for memory banks. ([`67b273d`](https://github.com/vectorize-io/hindsight/commit/67b273d))
**Improvements**
- Add retention modes to control how memories are extracted and stored. ([`fb31a35`](https://github.com/vectorize-io/hindsight/commit/fb31a35))
- Add offline (optional) database migrations to support restricted/air-gapped deployments. ([`233bd2e`](https://github.com/vectorize-io/hindsight/commit/233bd2e))
- Add database connection configuration options for more flexible deployments. ([`33fac2c`](https://github.com/vectorize-io/hindsight/commit/33fac2c))
- Load .env automatically on startup to simplify configuration. ([`c06d9b4`](https://github.com/vectorize-io/hindsight/commit/c06d9b4))
- Expose an operation ID from retain requests so async/background processing can be tracked. ([`1dacd0e`](https://github.com/vectorize-io/hindsight/commit/1dacd0e))
- Add per-request LLM token usage metrics for monitoring and cost tracking. ([`29a542d`](https://github.com/vectorize-io/hindsight/commit/29a542d))
- Add LLM call latency metrics for performance monitoring. ([`5e1f13e`](https://github.com/vectorize-io/hindsight/commit/5e1f13e))
- Include tenant in metrics labels for better multi-tenant observability. ([`1ffc2a4`](https://github.com/vectorize-io/hindsight/commit/1ffc2a4))
- Add async processing option to MCP retain tool for background retention workflows. ([`37fc7fb`](https://github.com/vectorize-io/hindsight/commit/37fc7fb))
**Bug Fixes**
- Fix extension loading in multi-worker deployments so all workers load extensions correctly. ([`f5f3fca`](https://github.com/vectorize-io/hindsight/commit/f5f3fca))
- Improve recall performance by batching recall queries. ([`5991308`](https://github.com/vectorize-io/hindsight/commit/5991308))
- Improve retrieval quality and stability for large memory banks (graph/MPFP retrieval fixes). ([`6232e69`](https://github.com/vectorize-io/hindsight/commit/6232e69))
- Fix entities list being limited to 100 entities. ([`26bf571`](https://github.com/vectorize-io/hindsight/commit/26bf571))
- Fix UI only showing the first 1000 memories. ([`67c1a42`](https://github.com/vectorize-io/hindsight/commit/67c1a42))
- Fix duplicated causal relationships and improve token usage during processing. ([`49e233c`](https://github.com/vectorize-io/hindsight/commit/49e233c))
- Improve causal link detection accuracy. ([`2a00df0`](https://github.com/vectorize-io/hindsight/commit/2a00df0))
- Make retain max completion tokens configurable to prevent truncation issues. ([`7715a51`](https://github.com/vectorize-io/hindsight/commit/7715a51))
- Fix Python SDK not sending the Authorization header, preventing authenticated requests. ([`39e3f7c`](https://github.com/vectorize-io/hindsight/commit/39e3f7c))
- Fix stats endpoint missing tenant authentication in multi-tenant setups. ([`d6ff191`](https://github.com/vectorize-io/hindsight/commit/d6ff191))
- Fix embedding dimension handling for tenant schemas in multi-tenant databases. ([`6fe9314`](https://github.com/vectorize-io/hindsight/commit/6fe9314))
- Fix Groq free-tier compatibility so requests work correctly. ([`d899d18`](https://github.com/vectorize-io/hindsight/commit/d899d18))
- Fix security vulnerability (qs / CVE-2025-15284). ([`b3becb6`](https://github.com/vectorize-io/hindsight/commit/b3becb6))
- Restore MCP tools for listing and creating memory banks. ([`9fd5679`](https://github.com/vectorize-io/hindsight/commit/9fd5679))
## [0.2.0](https://github.com/vectorize-io/hindsight/releases/tag/v0.2.0)
**Features**
- Add additional model provider support, including Anthropic Claude and LM Studio. ([`787ed60`](https://github.com/vectorize-io/hindsight/commit/787ed60))
- Add multi-bank access and new MCP tools for interacting with multiple memory banks via MCP. ([`6b5f593`](https://github.com/vectorize-io/hindsight/commit/6b5f593))
- Allow supplying custom entities when retaining memories via the retain endpoint. ([`dd59bc8`](https://github.com/vectorize-io/hindsight/commit/dd59bc8))
- Enhance the /reflect endpoint with max_tokens control and optional structured output responses. ([`d49e820`](https://github.com/vectorize-io/hindsight/commit/d49e820))
**Improvements**
- Improve local LLM support for reasoning-capable models and streamline Docker startup for local deployments. ([`eea0f27`](https://github.com/vectorize-io/hindsight/commit/eea0f27))
- Support operation validator extensions and return proper HTTP errors when validation fails. ([`ce45d30`](https://github.com/vectorize-io/hindsight/commit/ce45d30))
- Add configurable observation thresholds to control when observations are created/updated. ([`54e2df0`](https://github.com/vectorize-io/hindsight/commit/54e2df0))
- Improve graph visualization to the control plane for exploring memory relationships. ([`1a62069`](https://github.com/vectorize-io/hindsight/commit/1a62069))
**Bug Fixes**
- Fix MCP server lifecycle handling so MCP lifespan is correctly tied to the FastAPI app lifespan. ([`6b78f7d`](https://github.com/vectorize-io/hindsight/commit/6b78f7d))
## [0.1.15](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.15)
**Features**
- Add the ability to delete documents from the web UI. ([`f7ff32d`](https://github.com/vectorize-io/hindsight/commit/f7ff32d))
**Improvements**
- Improve the API health check endpoint and update the generated client APIs/types accordingly. ([`e06a612`](https://github.com/vectorize-io/hindsight/commit/e06a612))
## [0.1.14](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.14)
**Bug Fixes**
- Fixes the embedded “get-skill” installer so installing skills works correctly. ([`0b352d1`](https://github.com/vectorize-io/hindsight/commit/0b352d1))
## [0.1.13](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.13)
**Improvements**
- Improve reliability by surfacing task handler failures so retries can occur when processing fails. ([`904ea4d`](https://github.com/vectorize-io/hindsight/commit/904ea4d))
- Revamp the hindsight-embed component architecture, including a new daemon/client model and CLI updates for embedding workflows. ([`e6511e7`](https://github.com/vectorize-io/hindsight/commit/e6511e7))
**Bug Fixes**
- Fix memory retention so timestamps are correctly taken into account. ([`234d426`](https://github.com/vectorize-io/hindsight/commit/234d426))
## [0.1.12](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.12)
**Features**
- Added an extensions system for plugging in new operations/skills (including built-in tenant support). ([`2a0c490`](https://github.com/vectorize-io/hindsight/commit/2a0c490))
- Introduced the hindsight-embed tool and a native agentic skill for embedding/agent workflows. ([`da44a5e`](https://github.com/vectorize-io/hindsight/commit/da44a5e))
**Improvements**
- Improved reliability when parsing LLM JSON by retrying on parse errors and adding clearer diagnostics. ([`a831a7b`](https://github.com/vectorize-io/hindsight/commit/a831a7b))
**Bug Fixes**
- Fixed structured-output support for Ollama-based LLM providers. ([`32bca12`](https://github.com/vectorize-io/hindsight/commit/32bca12))
- Adjusted LLM validation to cap max completion tokens at 100 to prevent validation failures. ([`b94b5cf`](https://github.com/vectorize-io/hindsight/commit/b94b5cf))
## [0.1.11](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.11)
**Bug Fixes**
- Fixed the standalone Docker image and control plane standalone build process so standalone deployments build correctly. ([`2948cb6`](https://github.com/vectorize-io/hindsight/commit/2948cb6))
## [0.1.10](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.10)
*This release contains internal maintenance and infrastructure changes only.*
## [0.1.9](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.9)
**Features**
- Simplified local MCP installation and added a standalone UI option for easier setup. ([`1c6acc3`](https://github.com/vectorize-io/hindsight/commit/1c6acc3))
**Bug Fixes**
- Fixed the standalone Docker image so it builds and starts reliably. ([`b52eb90`](https://github.com/vectorize-io/hindsight/commit/b52eb90))
- Improved Docker runtime reliability by adding required system utilities (procps). ([`ae80876`](https://github.com/vectorize-io/hindsight/commit/ae80876))
## [0.1.8](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.8)
**Bug Fixes**
- Fix bank list responses when a bank has no name. ([`04f01ab`](https://github.com/vectorize-io/hindsight/commit/04f01ab))
- Fix failures when retaining memories asynchronously. ([`63f5138`](https://github.com/vectorize-io/hindsight/commit/63f5138))
- Fix a race condition in the bank selector when switching banks. ([`e468a4e`](https://github.com/vectorize-io/hindsight/commit/e468a4e))
## [0.1.7](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.7)
*This release contains internal maintenance and infrastructure changes only.*
## [0.1.6](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.6)
**Features**
- Added support for the Gemini 3 Pro and GPT-5.2 models. ([`bb1f9cb`](https://github.com/vectorize-io/hindsight/commit/bb1f9cb))
- Added a local MCP server option for running/connecting to Hindsight via MCP without a separate remote service. ([`7dd6853`](https://github.com/vectorize-io/hindsight/commit/7dd6853))
**Improvements**
- Updated the Postgres/pg0 dependency to a newer 0.11.x series for improved compatibility and stability. ([`47be07f`](https://github.com/vectorize-io/hindsight/commit/47be07f))
## [0.1.5](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.5)
**Features**
- Added LiteLLM integration so Hindsight can capture and manage memories from LiteLLM-based LLM calls. ([`dfccbf2`](https://github.com/vectorize-io/hindsight/commit/dfccbf2))
- Added an optional graph-based retriever (MPFP) to improve recall by leveraging relationships between memories. ([`7445cef`](https://github.com/vectorize-io/hindsight/commit/7445cef))
**Improvements**
- Switched the embedded Postgres layer to pg0-embedded for a smoother local/standalone experience. ([`94c2b85`](https://github.com/vectorize-io/hindsight/commit/94c2b85))
**Bug Fixes**
- Fixed repeated retries on 400 errors from the LLM, preventing unnecessary request loops and failures. ([`70983f5`](https://github.com/vectorize-io/hindsight/commit/70983f5))
- Fixed recall trace visualization in the control plane so search/recall debugging displays correctly. ([`922164e`](https://github.com/vectorize-io/hindsight/commit/922164e))
- Fixed the CLI installer to make installation more reliable. ([`158a6aa`](https://github.com/vectorize-io/hindsight/commit/158a6aa))
- Updated Next.js to patch security vulnerabilities (CVE-2025-55184, CVE-2025-55183). ([`f018cc5`](https://github.com/vectorize-io/hindsight/commit/f018cc5))
## [0.1.3](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.3)
**Improvements**
- Improved CLI and UI branding/polish, including new banner/logo assets and updated interface styling. ([`fa554b8`](https://github.com/vectorize-io/hindsight/commit/fa554b8))
## [0.1.2](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.2)
**Bug Fixes**
- Fixed the standalone Docker image so it builds/runs correctly. ([`1056a20`](https://github.com/vectorize-io/hindsight/commit/1056a20))

11
skills/hindsight-docs/references/changelog/integrations/ai-sdk.md Normal file
View file

@ -0,0 +1,11 @@
---
hide_table_of_contents: true
---
# AI SDK Integration Changelog
Changelog for [`@vectorize-io/hindsight-ai-sdk`](https://www.npmjs.com/package/@vectorize-io/hindsight-ai-sdk) — memory integration for Vercel AI SDK.
For the source code, see [`hindsight-integrations/ai-sdk`](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/ai-sdk).
← [Back to main changelog](../index.md)

11
skills/hindsight-docs/references/changelog/integrations/chat.md Normal file
View file

@ -0,0 +1,11 @@
---
hide_table_of_contents: true
---
# Chat SDK Integration Changelog
Changelog for [`@vectorize-io/hindsight-chat`](https://www.npmjs.com/package/@vectorize-io/hindsight-chat) — memory integration for Vercel Chat SDK.
For the source code, see [`hindsight-integrations/chat`](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/chat).
← [Back to main changelog](../index.md)

11
skills/hindsight-docs/references/changelog/integrations/crewai.md Normal file
View file

@ -0,0 +1,11 @@
---
hide_table_of_contents: true
---
# CrewAI Integration Changelog
Changelog for [`hindsight-crewai`](https://pypi.org/project/hindsight-crewai/) — persistent memory for CrewAI agents.
For the source code, see [`hindsight-integrations/crewai`](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/crewai).
← [Back to main changelog](../index.md)

11
skills/hindsight-docs/references/changelog/integrations/litellm.md Normal file
View file

@ -0,0 +1,11 @@
---
hide_table_of_contents: true
---
# LiteLLM Integration Changelog
Changelog for [`hindsight-litellm`](https://pypi.org/project/hindsight-litellm/) — universal LLM memory integration via LiteLLM.
For the source code, see [`hindsight-integrations/litellm`](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/litellm).
← [Back to main changelog](../index.md)

11
skills/hindsight-docs/references/changelog/integrations/openclaw.md Normal file
View file

@ -0,0 +1,11 @@
---
hide_table_of_contents: true
---
# OpenClaw Integration Changelog
Changelog for [`@vectorize-io/hindsight-openclaw`](https://www.npmjs.com/package/@vectorize-io/hindsight-openclaw) — Hindsight memory plugin for OpenClaw.
For the source code, see [`hindsight-integrations/openclaw`](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/openclaw).
← [Back to main changelog](../index.md)

11
skills/hindsight-docs/references/changelog/integrations/pydantic-ai.md Normal file
View file

@ -0,0 +1,11 @@
---
hide_table_of_contents: true
---
# Pydantic AI Integration Changelog
Changelog for [`hindsight-pydantic-ai`](https://pypi.org/project/hindsight-pydantic-ai/) — persistent memory tools for Pydantic AI agents.
For the source code, see [`hindsight-integrations/pydantic-ai`](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/pydantic-ai).
← [Back to main changelog](../index.md)

36
skills/hindsight-docs/references/developer/api/documents.md
View file

@ -79,6 +79,12 @@ hindsight memory retain my-bank "Meeting notes content..." --doc-id notes-2024-0
hindsight memory retain-files my-bank docs/
```
### Go
```go
# Section 'document-retain' not found in api/documents.go
```
## Update Documents
Re-retaining with the same document_id **replaces** the old content:
@ -125,6 +131,12 @@ hindsight memory retain my-bank "Project deadline: March 31" --doc-id project-pl
hindsight memory retain my-bank "Project deadline: April 15 (extended)" --doc-id project-plan
```
### Go
```go
# Section 'document-update' not found in api/documents.go
```
## Get Document
Retrieve a document's original text and metadata. This is useful for expanding document context after a recall operation returns memories with document references.
@ -179,6 +191,12 @@ console.log(`Created: ${doc.created_at}`);
hindsight document get my-bank meeting-2024-03-15
```
### Go
```go
# Section 'document-get' not found in api/documents.go
```
## Update Document
Update mutable fields on an existing document without re-processing the content. Currently supports updating `tags`.
@ -225,6 +243,12 @@ hindsight document update-tags my-bank meeting-2024-03-15 --tags team-a --tags t
hindsight document update-tags my-bank meeting-2024-03-15
```
### Go
```go
# Section 'document-update' not found in api/documents.go
```
:::info Observations are re-consolidated
When tags change, any consolidated observations derived from the document's memories are invalidated and queued for re-consolidation under the new tags. Co-source memories from other documents that shared those observations are also reset.
## Delete Document
@ -271,6 +295,12 @@ console.log(`Deleted ${deleteResult.memory_units_deleted} memories`);
hindsight document delete my-bank meeting-2024-03-15
```
### Go
```go
# Section 'document-delete' not found in api/documents.go
```
:::warning
Deleting a document permanently removes all memories extracted from it. This action cannot be undone.
## List Documents
@ -373,6 +403,12 @@ hindsight document list my-bank --q report
hindsight document list my-bank --tags team-a --tags team-b
```
### Go
```go
# Section 'document-list' not found in api/documents.go
```
### Filtering Options
| Parameter | Description |

41
skills/hindsight-docs/references/developer/api/main-methods.md
View file

@ -76,13 +76,19 @@ await client.retainBatch('my-bank', [
```bash
# Store a single fact
hindsight retain my-bank "Alice joined Google in March 2024 as a Senior ML Engineer"
hindsight memory retain my-bank "Alice joined Google in March 2024 as a Senior ML Engineer"
# Store from a file
hindsight retain my-bank --file conversation.txt --context "Daily standup"
hindsight memory retain-files my-bank conversation.txt --context "Daily standup"
# Store multiple files
hindsight retain my-bank --files docs/*.md
hindsight memory retain-files my-bank docs/
```
### Go
```go
# Section 'main-retain' not found in api/main-methods.go
```
**What happens:** Content is processed by an LLM to extract rich facts, identify entities, and build connections in a knowledge graph.
@ -166,16 +172,22 @@ for (const [entityId, entity] of Object.entries(entityResults.entities || {})) {
```bash
# Basic search
hindsight recall my-bank "What does Alice do at Google?"
hindsight memory recall my-bank "What does Alice do at Google?"
# Search with options
hindsight recall my-bank "What happened last spring?" \
hindsight memory recall my-bank "What happened last spring?" \
--budget high \
--max-tokens 8192 \
--fact-type world
--fact-type world,experience
# Verbose output (shows weights and sources)
hindsight recall my-bank "Tell me about Alice" -v
# Verbose output
hindsight memory recall my-bank "Tell me about Alice" -v
```
### Go
```go
# Section 'main-recall' not found in api/main-methods.go
```
**What happens:** Four search strategies (semantic, keyword, graph, temporal) run in parallel, results are fused and reranked.
@ -238,13 +250,16 @@ for (const fact of detailedResponse.based_on || []) {
```bash
# Basic reflect
hindsight reflect my-bank "Should we adopt TypeScript for our backend?"
# Verbose output (shows sources and observations)
hindsight reflect my-bank "What are Alice's strengths for the team lead role?" -v
hindsight memory reflect my-bank "Should we adopt TypeScript for our backend?"
# With higher reasoning budget
hindsight reflect my-bank "Analyze our tech stack" --budget high
hindsight memory reflect my-bank "Analyze our tech stack" --budget high
```
### Go
```go
# Section 'main-reflect' not found in api/main-methods.go
```
**What happens:** Memories and observations are recalled, bank disposition is applied, and the LLM reasons through the evidence to generate a response.

129
skills/hindsight-docs/references/developer/api/memory-banks.md
View file

@ -42,9 +42,15 @@ await client.createBank('my-bank');
hindsight bank create my-bank
```
### Go
```go
# Section 'create-bank' not found in api/memory-banks.go
```
## Bank Configuration
Each memory bank can be configured independently per operation. Configuration can be set via the [bank config API](#updating-configuration), the [Control Plane UI](/), or [server-wide environment variables](/developer/configuration).
Each memory bank can be configured independently per operation. Configuration can be set via the [bank config API](#updating-configuration), the Control Plane UI, or [server-wide environment variables](../configuration.md).
### retain_mission {#retain-configuration}
@ -77,7 +83,7 @@ Maximum number of characters per chunk when splitting content for fact extractio
Default: `3000`
See [Retain configuration](/developer/configuration#retain) for environment variable names and defaults.
See [Retain configuration](../configuration.md#retain) for environment variable names and defaults.
### entity_labels {#entity-labels}
@ -172,7 +178,7 @@ Total token budget for source facts included with observations in the consolidat
Per-observation token cap for source facts in the consolidation prompt. Each observation independently gets at most this many tokens of source facts, preventing a single observation with many source facts from consuming the entire budget. `-1` = unlimited. Leave unset to use the server default (`256`).
See [Observations configuration](/developer/configuration#observations) for environment variable names and defaults.
See [Observations configuration](../configuration.md#observations) for environment variable names and defaults.
### reflect_mission
@ -214,6 +220,22 @@ await client.updateBankConfig('architect-bank', {
});
```
### CLI
```bash
hindsight bank create architect-bank \
--mission "You're a senior software architect - keep track of system designs, technology decisions, and architectural patterns. Prefer simplicity over cutting-edge." \
--skepticism 4 \
--literalism 4 \
--empathy 2
```
### Go
```go
# Section 'bank-with-disposition' not found in api/memory-banks.go
```
| Value | Behaviour |
|-------|-----------|
| `1` | Trusting — accepts information at face value |
@ -300,6 +322,24 @@ await client.updateBankConfig('my-bank', {
});
```
### CLI
```bash
hindsight bank set-config my-bank \
--retain-mission "Always include technical decisions, API design choices, and architectural trade-offs. Ignore meeting logistics and social exchanges." \
--retain-extraction-mode verbose \
--observations-mission "Observations are stable facts about people and projects. Always include preferences, skills, and recurring patterns. Ignore one-off events." \
--disposition-skepticism 4 \
--disposition-literalism 4 \
--disposition-empathy 2
```
### Go
```go
# Section 'update-bank-config' not found in api/memory-banks.go
```
You can update any subset of fields — only the keys you provide are changed.
### Reading the Current Configuration
@ -322,6 +362,22 @@ const { config, overrides } = await client.getBankConfig('my-bank');
// overrides — only fields overridden at the bank level
```
### CLI
```bash
# Returns resolved config (server defaults merged with bank overrides)
hindsight bank config my-bank
# Show only bank-specific overrides
hindsight bank config my-bank --overrides-only
```
### Go
```go
# Section 'get-bank-config' not found in api/memory-banks.go
```
The response distinguishes:
- **`config`** — the fully resolved configuration (server defaults merged with bank overrides)
- **`overrides`** — only the fields explicitly overridden for this bank
@ -342,9 +398,22 @@ client.reset_bank_config("my-bank")
await client.resetBankConfig('my-bank');
```
### CLI
```bash
# Remove all bank-level overrides, reverting to server defaults
hindsight bank reset-config my-bank -y
```
### Go
```go
# Section 'reset-bank-config' not found in api/memory-banks.go
```
This removes all bank-level overrides. The bank reverts to server-wide defaults (set via environment variables).
You can also update configuration directly from the [Control Plane UI](/) — navigate to a bank and open the **Configuration** tab.
You can also update configuration directly from the Control Plane UI — navigate to a bank and open the **Configuration** tab.
---
@ -391,6 +460,21 @@ const directive = await client.createDirective(
console.log(`Created directive: ${directive.id}`);
```
### CLI
```bash
# Create a directive (hard rule for reflect)
hindsight directive create "$BANK_ID" \
"Formal Language" \
"Always respond in formal English, avoiding slang and colloquialisms."
```
### Go
```go
# Section 'create-directive' not found in api/directives.go
```
### Listing Directives
### Python
@ -414,6 +498,19 @@ for (const d of directives.items) {
}
```
### CLI
```bash
# List all directives in a bank
hindsight directive list "$BANK_ID"
```
### Go
```go
# Section 'list-directives' not found in api/directives.go
```
### Updating Directives
### Python
@ -440,6 +537,18 @@ const updated = await client.updateDirective(BANK_ID, directiveId, {
console.log(`Directive active: ${updated.is_active}`);
```
### CLI
```bash
# Section 'update-directive' not found in api/directives.sh
```
### Go
```go
# Section 'update-directive' not found in api/directives.go
```
### Deleting Directives
### Python
@ -459,6 +568,18 @@ client.delete_directive(
await client.deleteDirective(BANK_ID, directiveId);
```
### CLI
```bash
# Section 'delete-directive' not found in api/directives.sh
```
### Go
```go
# Section 'delete-directive' not found in api/directives.go
```
### Directives vs Disposition
| Aspect | Directives | Disposition |

239
skills/hindsight-docs/references/developer/api/mental-models.md
View file

@ -59,20 +59,34 @@ result = client.create_mental_model(
print(f"Operation ID: {result.operation_id}")
```
### Node.js
```javascript
// Create a mental model (runs reflect in background)
const result = await client.createMentalModel(
BANK_ID,
'Team Communication Preferences',
'How does the team prefer to communicate?',
{ tags: ['team', 'communication'] },
);
// Returns an operation_id — check operations endpoint for completion
console.log(`Operation ID: ${result.operation_id}`);
```
### CLI
```bash
# Create a mental model (async operation)
curl -X POST "http://localhost:8888/v1/default/banks/my-bank/mental-models" \
-H "Content-Type: application/json" \
-d '{
"name": "Team Communication Preferences",
"source_query": "How does the team prefer to communicate?",
"tags": ["team"]
}'
# Create a mental model (runs reflect in background)
hindsight mental-model create "$BANK_ID" \
"Team Communication Preferences" \
"How does the team prefer to communicate?"
```
# Response: {"operation_id": "op-123"}
# Use the operations endpoint to check completion
### Go
```go
# Section 'create-mental-model' not found in api/mental-models.go
```
### Parameters
@ -81,12 +95,65 @@ curl -X POST "http://localhost:8888/v1/default/banks/my-bank/mental-models" \
|-----------|------|----------|-------------|
| `name` | string | Yes | Human-readable name for the mental model |
| `source_query` | string | Yes | The query to run to generate content |
| `id` | string | No | Custom ID for the mental model (alphanumeric lowercase with hyphens). Auto-generated if omitted. |
| `tags` | list | No | Tags for filtering during retrieval |
| `max_tokens` | int | No | Maximum tokens for the mental model content |
| `trigger` | object | No | Trigger settings (see [Automatic Refresh](#automatic-refresh)) |
---
## Create with Custom ID
Assign a stable, human-readable ID to a mental model so you can retrieve or update it by name instead of relying on the auto-generated UUID:
### Python
```python
# Create a mental model with a specific custom ID
result_with_id = client.create_mental_model(
bank_id=BANK_ID,
name="Communication Policy",
source_query="What are the team's communication guidelines?",
id="communication-policy"
)
print(f"Created with custom ID: {result_with_id.operation_id}")
```
### Node.js
```javascript
// Create a mental model with a specific custom ID
const resultWithId = await client.createMentalModel(
BANK_ID,
'Communication Policy',
"What are the team's communication guidelines?",
{ id: 'communication-policy' },
);
console.log(`Created with custom ID: ${resultWithId.operation_id}`);
```
### CLI
```bash
# Create a mental model with a specific custom ID
hindsight mental-model create "$BANK_ID" \
"Communication Policy" \
"What are the team's communication guidelines?" \
--id communication-policy
```
### Go
```go
# Section 'create-mental-model-with-id' not found in api/mental-models.go
```
:::tip
Custom IDs must be lowercase alphanumeric and may contain hyphens (e.g. `team-policies`, `q4-status`). If a mental model with that ID already exists, the request is rejected.
---
## Automatic Refresh
Mental models can be configured to **automatically refresh** when observations are updated. This keeps them in sync with the latest knowledge without manual intervention.
@ -114,17 +181,34 @@ result = client.create_mental_model(
print(f"Operation ID: {result.operation_id}")
```
### Node.js
```javascript
// Create a mental model with automatic refresh enabled
const result2 = await client.createMentalModel(
BANK_ID,
'Project Status',
'What is the current project status?',
{ trigger: { refreshAfterConsolidation: true } },
);
// This mental model will automatically refresh when observations are updated
console.log(`Operation ID: ${result2.operation_id}`);
```
### CLI
```bash
# Create a mental model with automatic refresh enabled
curl -X POST "http://localhost:8888/v1/default/banks/my-bank/mental-models" \
-H "Content-Type: application/json" \
-d '{
"name": "Project Status",
"source_query": "What is the current project status?",
"trigger": {"refresh_after_consolidation": true}
}'
# Create a mental model and get its ID for subsequent operations
hindsight mental-model create "$BANK_ID" \
"Project Status" \
"What is the current project status?"
```
### Go
```go
# Section 'create-mental-model-with-trigger' not found in api/mental-models.go
```
### When to Use Automatic Refresh
@ -152,10 +236,28 @@ for mental_model in mental_models.items:
print(f"- {mental_model.name}: {mental_model.source_query}")
```
### Node.js
```javascript
// List all mental models in a bank
const mentalModels = await client.listMentalModels(BANK_ID);
for (const mm of mentalModels.items) {
console.log(`- ${mm.name}: ${mm.source_query}`);
}
```
### CLI
```bash
curl "http://localhost:8888/v1/default/banks/my-bank/mental-models"
# List all mental models in a bank
hindsight mental-model list "$BANK_ID"
```
### Go
```go
# Section 'list-mental-models' not found in api/mental-models.go
```
---
@ -168,10 +270,27 @@ curl "http://localhost:8888/v1/default/banks/my-bank/mental-models"
# Section 'get-mental-model' not found in api/mental-models.py
```
### Node.js
```javascript
// Get a specific mental model
const mentalModel = await client.getMentalModel(BANK_ID, mentalModelId);
console.log(`Name: ${mentalModel.name}`);
console.log(`Content: ${mentalModel.content}`);
console.log(`Last refreshed: ${mentalModel.last_refreshed_at}`);
```
### CLI
```bash
curl "http://localhost:8888/v1/default/banks/my-bank/mental-models/{mental_model_id}"
# Section 'get-mental-model' not found in api/mental-models.sh
```
### Go
```go
# Section 'get-mental-model' not found in api/mental-models.go
```
### Response Fields
@ -200,10 +319,25 @@ Re-run the source query to update the mental model with current knowledge:
# Section 'refresh-mental-model' not found in api/mental-models.py
```
### Node.js
```javascript
// Refresh a mental model to update with current knowledge
const refreshResult = await client.refreshMentalModel(BANK_ID, mentalModelId);
console.log(`Refresh operation ID: ${refreshResult.operation_id}`);
```
### CLI
```bash
curl -X POST "http://localhost:8888/v1/default/banks/my-bank/mental-models/{mental_model_id}/refresh"
# Section 'refresh-mental-model' not found in api/mental-models.sh
```
### Go
```go
# Section 'refresh-mental-model' not found in api/mental-models.go
```
Refreshing is useful when:
@ -223,12 +357,28 @@ Update the mental model's name:
# Section 'update-mental-model' not found in api/mental-models.py
```
### Node.js
```javascript
// Update a mental model's metadata
const updated = await client.updateMentalModel(BANK_ID, mentalModelId, {
name: 'Updated Team Communication Preferences',
trigger: { refresh_after_consolidation: true },
});
console.log(`Updated name: ${updated.name}`);
```
### CLI
```bash
curl -X PATCH "http://localhost:8888/v1/default/banks/my-bank/mental-models/{mental_model_id}" \
-H "Content-Type: application/json" \
-d '{"name": "Updated Team Communication Preferences"}'
# Section 'update-mental-model' not found in api/mental-models.sh
```
### Go
```go
# Section 'update-mental-model' not found in api/mental-models.go
```
---
@ -241,10 +391,23 @@ curl -X PATCH "http://localhost:8888/v1/default/banks/my-bank/mental-models/{men
# Section 'delete-mental-model' not found in api/mental-models.py
```
### Node.js
```javascript
// Delete a mental model
await client.deleteMentalModel(BANK_ID, mentalModelId);
```
### CLI
```bash
curl -X DELETE "http://localhost:8888/v1/default/banks/my-bank/mental-models/{mental_model_id}"
# Section 'delete-mental-model' not found in api/mental-models.sh
```
### Go
```go
# Section 'delete-mental-model' not found in api/mental-models.go
```
---
@ -287,6 +450,30 @@ Every time a mental model's content changes (via refresh or manual update), the
# Section 'get-mental-model-history' not found in api/mental-models.py
```
### Node.js
```javascript
// Get the change history of a mental model
const history = await client.getMentalModelHistory(BANK_ID, mentalModelId);
for (const entry of history) {
console.log(`Changed at: ${entry.changed_at}`);
console.log(`Previous content: ${entry.previous_content}`);
}
```
### CLI
```bash
# Section 'get-mental-model-history' not found in api/mental-models.sh
```
### Go
```go
# Section 'get-mental-model-history' not found in api/mental-models.go
```
### Response
The endpoint returns a list of history entries, most recent first:
@ -316,5 +503,5 @@ History tracking is enabled by default. Set `HINDSIGHT_API_ENABLE_MENTAL_MODEL_H
## Next Steps
- [**Reflect**](./reflect) — How the agentic loop uses mental models
- [**Observations**](/developer/observations) — How knowledge is consolidated
- [**Observations**](../observations.md) — How knowledge is consolidated
- [**Operations**](./operations) — Track async mental model creation

14
skills/hindsight-docs/references/developer/api/quickstart.md
View file

@ -41,7 +41,7 @@ docker run --rm -it --pull always -p 8888:8888 -p 9999:9999 \
> **💡 LLM Provider**
>
Hindsight requires an LLM with structured output support. Recommended: **Groq** with `gpt-oss-20b` for fast, cost-effective inference.
See [LLM Providers](/developer/models#llm) for more details.
See [LLM Providers](../models.md#llm) for more details.
---
## Use the Client
@ -105,6 +105,16 @@ hindsight memory recall my-bank "What does Alice do?"
hindsight memory reflect my-bank "Tell me about Alice"
```
### Go
```bash
go get github.com/vectorize-io/hindsight/hindsight-clients/go
```
```go
# Section 'quickstart-full' not found in api/quickstart.go
```
---
## What's Happening
@ -127,4 +137,4 @@ hindsight memory reflect my-bank "Tell me about Alice"
- [**Recall**](./recall) — Search and retrieval strategies
- [**Reflect**](./reflect) — Disposition-aware reasoning
- [**Memory Banks**](./memory-banks) — Configure disposition and mission
- [**Server Deployment**](/developer/installation) — Docker Compose, Helm, and production setup
- [**Server Deployment**](../installation.md) — Docker Compose, Helm, and production setup

184
skills/hindsight-docs/references/developer/api/recall.md
View file

@ -8,7 +8,7 @@ When you **recall**, Hindsight runs four retrieval strategies in parallel — se
{/* Import raw source files */}
:::info How Recall Works
Learn about the four retrieval strategies (semantic, keyword, graph, temporal) and RRF fusion in the [Recall Architecture](/developer/retrieval) guide.
Learn about the four retrieval strategies (semantic, keyword, graph, temporal) and RRF fusion in the [Recall Architecture](../retrieval.md) guide.
> **💡 Prerequisites**
>
Make sure you've completed the [Quick Start](./quickstart) to install the client and start the server.
@ -72,6 +72,12 @@ const response = await client.recall('my-bank', 'What does Alice do?');
hindsight memory recall my-bank "What does Alice do?"
```
### Go
```go
# Section 'recall-basic' not found in api/recall.go
```
---
## Parameters
@ -113,12 +119,36 @@ observations = client.recall(
)
```
### Node.js
```javascript
await client.recall('my-bank', 'query', { types: ['world'] });
```
```javascript
await client.recall('my-bank', 'query', { types: ['experience'] });
```
```javascript
await client.recall('my-bank', 'query', { types: ['observation'] });
```
### CLI
```bash
hindsight memory recall my-bank "query" --fact-type world,observation
```
### Go
```go
# Section 'recall-world-only' not found in api/recall.go
```
```go
# Section 'recall-experience-only' not found in api/recall.go
```
```go
# Section 'recall-observations-only' not found in api/recall.go
```
> **💡 About Observations**
>
Observations are consolidated knowledge synthesized from multiple facts over time — patterns, preferences, and learnings the memory bank has built up. They are created automatically in the background after retain operations.
@ -146,6 +176,22 @@ const quickResults = await client.recall('my-bank', "Alice's email", { budget: '
const deepResults = await client.recall('my-bank', 'How are Alice and Bob connected?', { budget: 'high' });
```
### CLI
```bash
# Quick lookup
hindsight memory recall my-bank "Alice's email" --budget low
# Deep exploration
hindsight memory recall my-bank "How are Alice and Bob connected?" --budget high
```
### Go
```go
# Section 'recall-budget-levels' not found in api/recall.go
```
### max_tokens
The maximum number of tokens the returned facts can collectively occupy. Defaults to `4096`. Only the `text` field of each fact is counted toward this budget — metadata, tags, entities, and other fields are not included. After reranking, facts are included in relevance order until this budget is exhausted — so you always get the most relevant memories that fit. Hindsight is designed for agents, which think in tokens rather than result counts: set `max_tokens` to however much of your context window you want to allocate to memories.
@ -160,6 +206,32 @@ results = client.recall(bank_id="my-bank", query="What do I know about Alice?",
results = client.recall(bank_id="my-bank", query="Alice's email", max_tokens=500)
```
### Node.js
```javascript
// Fill up to 4K tokens of context with relevant memories
await client.recall('my-bank', 'What do I know about Alice?', { maxTokens: 4096 });
// Smaller budget for quick lookups
await client.recall('my-bank', "Alice's email", { maxTokens: 500 });
```
### CLI
```bash
# Fill up to 4K tokens of context with relevant memories
hindsight memory recall my-bank "What do I know about Alice?" --max-tokens 4096
# Smaller budget for quick lookups
hindsight memory recall my-bank "Alice's email" --max-tokens 500
```
### Go
```go
# Section 'recall-token-budget' not found in api/recall.go
```
### query_timestamp
An ISO 8601 datetime representing when the query is being asked, from the user's perspective. When provided, it is used as the anchor for resolving relative temporal expressions in the query — for example, if the query says "last month" and `query_timestamp` is `2023-05-30`, the temporal search window becomes approximately April 2023. Without it, the server's current time is used as the anchor. This field matters most for replaying historical conversations or building agents that need time-anchored recall.
@ -222,6 +294,20 @@ for (const obs of obsResponse.results) {
}
```
### CLI
```bash
# Recall observations with source facts
hindsight memory recall my-bank "What patterns have I learned about Alice?" \
--fact-type observation
```
### Go
```go
# Section 'recall-source-facts' not found in api/recall.go
```
#### entities
Enabled by default. When active, each returned fact includes the canonical names of entities associated with it. Set to `null` to skip the entity JOIN query and reduce response size. The `max_tokens` sub-option (default `500`) is a future-facing guard for entity data.
@ -254,6 +340,8 @@ Consider a bank with these four memories:
Returns memories that have **at least one** matching tag, plus untagged memories.
### Python
```python
response = client.recall(
bank_id="my-bank",
@ -268,12 +356,36 @@ response = client.recall(
# [match] "Company policy: no meetings on Fridays" — untagged, included by default
```
### Node.js
```javascript
await client.recall('my-bank', 'communication preferences', {
tags: ['user:alice'],
tagsMatch: 'any'
});
```
### CLI
```bash
hindsight memory recall my-bank "communication preferences" \
--tags "user:alice" --tags-match any
```
### Go
```go
# Section 'recall-with-tags' not found in api/recall.go
```
Use this for **shared global knowledge + user-specific** patterns, where untagged memories represent information everyone should see.
#### `any_strict` — OR matching, excludes untagged
Same as `any` but untagged memories are excluded.
### Python
```python
response = client.recall(
bank_id="my-bank",
@ -288,12 +400,36 @@ response = client.recall(
# [no match] "Company policy: no meetings on Fridays" — untagged, excluded
```
### Node.js
```javascript
await client.recall('my-bank', 'communication preferences', {
tags: ['user:alice'],
tagsMatch: 'any_strict'
});
```
### CLI
```bash
hindsight memory recall my-bank "communication preferences" \
--tags "user:alice" --tags-match any_strict
```
### Go
```go
# Section 'recall-tags-strict' not found in api/recall.go
```
Use this when memories are **fully partitioned by tags** and untagged memories should never be visible.
#### `all` — AND matching, includes untagged
Returns memories that have **every** specified tag, plus untagged memories.
### Python
```python
response = client.recall(
bank_id="my-bank",
@ -308,12 +444,36 @@ response = client.recall(
# [match] "Company policy: no meetings on Fridays" — untagged, included by default
```
### Node.js
```javascript
await client.recall('my-bank', 'communication tools', {
tags: ['user:alice', 'team'],
tagsMatch: 'all'
});
```
### CLI
```bash
hindsight memory recall my-bank "communication tools" \
--tags "user:alice,team" --tags-match all
```
### Go
```go
# Section 'recall-tags-all-mode' not found in api/recall.go
```
Use this when memories must belong to a **specific intersection** of scopes (e.g., only memories relevant to both a user and a project), while still surfacing shared global knowledge.
#### `all_strict` — AND matching, excludes untagged
Returns memories that have **every** specified tag, and excludes untagged memories.
### Python
```python
response = client.recall(
bank_id="my-bank",
@ -328,6 +488,28 @@ response = client.recall(
# [no match] "Company policy: no meetings on Fridays" — untagged, excluded
```
### Node.js
```javascript
await client.recall('my-bank', 'communication tools', {
tags: ['user:alice', 'team'],
tagsMatch: 'all_strict'
});
```
### CLI
```bash
hindsight memory recall my-bank "communication tools" \
--tags "user:alice,team" --tags-match all_strict
```
### Go
```go
# Section 'recall-tags-all' not found in api/recall.go
```
Use this for strict scope enforcement where a memory must explicitly belong to **all** specified contexts.
> **💡 Extra tags are fine**

75
skills/hindsight-docs/references/developer/api/reflect.md
View file

@ -8,7 +8,7 @@ When you call **reflect**, Hindsight runs an agentic loop that autonomously sear
{/* Import raw source files */}
:::info How Reflect Works
Learn about disposition-driven reasoning in the [Reflect Architecture](/developer/reflect) guide.
Learn about disposition-driven reasoning in the [Reflect Architecture](../reflect.md) guide.
> **💡 Prerequisites**
>
Make sure you've completed the [Quick Start](./quickstart) to install the client and start the server.
@ -32,6 +32,12 @@ await client.reflect('my-bank', 'What should I know about Alice?');
hindsight memory reflect my-bank "What do you know about Alice?"
```
### Go
```go
# Section 'reflect-basic' not found in api/reflect.go
```
---
## Parameters
@ -63,6 +69,18 @@ const response = await client.reflect('my-bank', 'What do you think about remote
});
```
### CLI
```bash
hindsight memory reflect my-bank "Summarize my week" --budget high --max-tokens 8192
```
### Go
```go
# Section 'reflect-with-params' not found in api/reflect.go
```
### max_tokens
Limits the length of the final generated response. Defaults to `4096`. This does not affect how much the agent can retrieve during the agentic loop — only the final answer length.
@ -147,6 +165,12 @@ hindsight memory reflect hiring-team \
rm -f schema.json
```
### Go
```go
# Section 'reflect-structured-output' not found in api/reflect.go
```
### tags
Filters which memories the agent can access during reflection. Works identically to [recall tags](./recall#tags) — only memories matching the specified tags are considered. The `tags_match` parameter controls the matching logic (`any`, `all`, `any_strict`, `all_strict`) with the same semantics as recall.
@ -163,6 +187,29 @@ response = client.reflect(
)
```
### Node.js
```javascript
// Filter reflect to only use memories tagged for a specific user
await client.reflect('my-bank', 'What feedback did the user give?', {
tags: ['user:alice'],
tagsMatch: 'any_strict'
});
```
### CLI
```bash
hindsight memory reflect my-bank "What feedback did the user give?" \
--tags "user:alice" --tags-match any_strict
```
### Go
```go
# Section 'reflect-with-tags' not found in api/reflect.go
```
### include
Controls optional supplementary data returned alongside the main response.
@ -187,6 +234,32 @@ for fact in (response.based_on.memories if response.based_on else []):
print(f" - [{fact.type}] {fact.text}")
```
### Node.js
```javascript
const sourcesResponse = await client.reflect('my-bank', 'Tell me about Alice', {
includeFacts: true
});
console.log('Response:', sourcesResponse.text);
console.log('\nBased on:');
for (const fact of (sourcesResponse.based_on?.memories || [])) {
console.log(` - [${fact.type}] ${fact.text}`);
}
```
### CLI
```bash
hindsight memory reflect my-bank "Tell me about Alice" --include-facts
```
### Go
```go
# Section 'reflect-sources' not found in api/reflect.go
```
#### include.tool_calls
When enabled, the response includes a `trace` object with the full execution log of every tool call and LLM call made during the agentic loop, including inputs, outputs, and durations. Set `output: false` to include only tool inputs for a smaller payload. Useful for debugging why the agent reached a particular conclusion.

141
skills/hindsight-docs/references/developer/api/retain.md
View file

@ -8,7 +8,7 @@ When you **retain** content, Hindsight doesn't just store the raw text—it inte
{/* Import raw source files */}
:::info How Retain Works
Learn about fact extraction, entity resolution, and graph construction in the [Retain Architecture](/developer/retain) guide.
Learn about fact extraction, entity resolution, and graph construction in the [Retain Architecture](../retain.md) guide.
> **💡 Prerequisites**
>
Make sure you've completed the [Quick Start](./quickstart) to install the client and start the server.
@ -37,6 +37,12 @@ await client.retain('my-bank', 'Alice works at Google as a software engineer');
hindsight memory retain my-bank "Alice works at Google as a software engineer"
```
### Go
```go
# Section 'retain-basic' not found in api/retain.go
```
### Retaining a Conversation
A full conversation should be retained as a single item. The LLM can parse any format — plain text, JSON, Markdown, or any structured representation — as long as it clearly conveys who said what and when. The example below uses a simple `Name (timestamp): text` format.
@ -85,6 +91,27 @@ await client.retain('my-bank', conversation, {
});
```
### CLI
```bash
# Retain an entire conversation as a single document.
CONVERSATION="Alice (2024-03-15T09:00:00Z): Hi Bob! Did you end up going to the doctor last week?
Bob (2024-03-15T09:01:00Z): Yes, finally. Turns out I have a mild peanut allergy.
Alice (2024-03-15T09:02:00Z): Oh no! Are you okay?
Bob (2024-03-15T09:03:00Z): Yeah, nothing serious. Just need to carry an antihistamine.
Alice (2024-03-15T09:04:00Z): Good to know. We'll avoid peanuts at the team lunch."
hindsight memory retain my-bank "$CONVERSATION" \
--context "team chat" \
--doc-id "chat-2024-03-15-alice-bob"
```
### Go
```go
# Section 'retain-conversation' not found in api/retain.go
```
When the conversation grows — a new message arrives — just retain again with the full updated content and the same `document_id`. Hindsight will delete the previous version and reprocess from scratch, so memories always reflect the latest state of the conversation.
---
@ -140,6 +167,12 @@ hindsight memory retain my-bank "Alice got promoted" \
--context "career update"
```
### Go
```go
# Section 'retain-with-context' not found in api/retain.go
```
### metadata
Arbitrary key-value string pairs that provide context about this item. For example: `{"source": "slack", "channel": "engineering", "thread_id": "T123"}`. Metadata is included in the fact extraction prompt, so the LLM can use it as additional context when extracting facts — for instance, knowing the document title or source can improve accuracy. It is also stored on each memory unit and returned with every recalled memory, letting you do client-side filtering or static enrichment without extra lookups — for example, linking a memory back to its source URL, thread ID, or any application-specific identifier.
@ -263,6 +296,24 @@ await client.retainBatch('my-bank', [
]);
```
### CLI
```bash
# Batch ingestion via individual retain calls (CLI processes items one at a time)
hindsight memory retain my-bank "Alice works at Google" \
--context "career" --doc-id "conversation_001_msg_1"
hindsight memory retain my-bank "Bob is a data scientist at Meta" \
--context "career" --doc-id "conversation_001_msg_2"
hindsight memory retain my-bank "Alice and Bob are friends" \
--context "relationship" --doc-id "conversation_001_msg_3"
```
### Go
```go
# Section 'retain-batch' not found in api/retain.go
```
---
## Files
@ -271,28 +322,6 @@ Upload files directly — Hindsight converts them to text and extracts memories
**Supported formats:** PDF, DOCX, DOC, PPTX, PPT, XLSX, XLS, images (JPG, PNG, GIF, etc. — OCR), audio (MP3, WAV, FLAC, etc. — transcription), HTML, and plain text formats (TXT, MD, CSV, JSON, YAML, etc.)
### CLI
```bash
# Upload a single file (PDF, DOCX, PPTX, XLSX, images, audio, and more)
hindsight memory retain-files my-bank "$SAMPLE_FILE"
# Upload a directory of files
hindsight memory retain-files my-bank "$SCRIPT_DIR/"
# Queue files for background processing (returns immediately)
hindsight memory retain-files my-bank "$SCRIPT_DIR/" --async
```
### HTTP
```bash
# Via HTTP API (multipart/form-data)
curl -X POST "${HINDSIGHT_URL}/v1/default/banks/my-bank/files/retain" \
-F "files=@${SAMPLE_FILE};type=application/octet-stream" \
-F "request={\"files_metadata\": [{\"context\": \"quarterly report\"}]}"
```
### Python
```python
@ -324,6 +353,25 @@ const result = await client.retainFiles('my-bank', [
console.log(result.operation_ids); // Track processing via the operations endpoint
```
### CLI
```bash
# Upload a single file (PDF, DOCX, PPTX, XLSX, images, audio, and more)
hindsight memory retain-files my-bank "$SAMPLE_FILE"
# Upload a directory of files
hindsight memory retain-files my-bank "$SCRIPT_DIR/"
# Queue files for background processing (returns immediately)
hindsight memory retain-files my-bank "$SCRIPT_DIR/" --async
```
### Go
```go
# Section 'retain-files' not found in api/retain.go
```
The file retain endpoint always returns asynchronously. The response contains `operation_ids` — one per uploaded file — which you can poll via `GET /v1/default/banks/{bank_id}/operations` to track progress.
Upload up to 10 files per request (max 100 MB total). Each file becomes a separate document with optional per-file metadata:
@ -347,6 +395,41 @@ result = client.retain_files(
print(result.operation_ids) # One operation ID per file
```
### Node.js
```javascript
// Upload multiple files with per-file metadata (up to 10 files per request)
const batchResult = await client.retainFiles('my-bank', [
new File([pdfBytes], 'report.pdf'),
new File([pdfBytes], 'notes.pdf'),
], {
filesMetadata: [
{ context: 'quarterly report', document_id: 'q1-report', tags: ['project:alpha'] },
{ context: 'meeting notes', document_id: 'q1-notes', tags: ['project:alpha'] },
]
});
console.log(batchResult.operation_ids); // One operation ID per file
```
### CLI
```bash
# Upload a single file (PDF, DOCX, PPTX, XLSX, images, audio, and more)
hindsight memory retain-files my-bank "$SAMPLE_FILE"
# Upload a directory of files
hindsight memory retain-files my-bank "$SCRIPT_DIR/"
# Queue files for background processing (returns immediately)
hindsight memory retain-files my-bank "$SCRIPT_DIR/" --async
```
### Go
```go
# Section 'retain-files' not found in api/retain.go
```
:::info File Storage
Uploaded files are stored server-side (PostgreSQL by default, or S3/GCS/Azure for production). Configure storage via `HINDSIGHT_API_FILE_STORAGE_TYPE`. See [Configuration](../configuration#file-processing) for details.
---
@ -384,6 +467,18 @@ await client.retainBatch('my-bank', [
});
```
### CLI
```bash
hindsight memory retain my-bank "Meeting notes" --async
```
### Go
```go
# Section 'retain-async' not found in api/retain.go
```
When `async: true`, the call returns immediately with an `operation_id`. Processing runs in the background via the worker service. No `usage` metrics are returned for async operations.
### Cut Costs 50% with Provider Batch APIs

4
skills/hindsight-docs/references/developer/configuration.md
View file

@ -574,7 +574,7 @@ Controls the retain (memory ingestion) pipeline.
| `HINDSIGHT_API_RETAIN_BATCH_ENABLED` | Use LLM Batch API for fact extraction (50% cost savings, only with async operations) | `false` |
| `HINDSIGHT_API_RETAIN_BATCH_POLL_INTERVAL_SECONDS` | Batch API polling interval in seconds | `60` |
> **Entity labels** (`entity_labels`) and **free-form entity extraction** (`entities_allow_free_form`) are configured per bank via the [bank config API](/developer/api/memory-banks#retain-configuration), not as global environment variables — each bank can have its own controlled vocabulary. See [Entity Labels](/developer/retain#entity-labels) for details.
> **Entity labels** (`entity_labels`) and **free-form entity extraction** (`entities_allow_free_form`) are configured per bank via the [bank config API](api/memory-banks.md#retain-configuration), not as global environment variables — each bank can have its own controlled vocabulary. See [Entity Labels](retain.md#entity-labels) for details.
#### Customizing retain: when to use what
@ -646,8 +646,6 @@ client.retain(bank_id, items=[{"content": "...document text..."}], strategy="doc
If no `strategy` is specified in a retain call, `retain_default_strategy` is used. If neither is set, the bank/global config applies directly.
> **Note on chunk size and retrieval fairness**: When mixing strategies with very different chunk sizes in the same bank, `chunks` and `verbatim` memories participate only in semantic retrieval (not entity graph or temporal paths). Smaller chunk sizes (e.g., 800 chars) produce more targeted embeddings and are recommended for document strategies to keep scores comparable with LLM-extracted facts.
**`HINDSIGHT_API_RETAIN_EXTRACTION_MODE=chunks` — zero LLM cost**
Each chunk is stored as-is with no LLM call whatsoever. No entity extraction, no temporal indexing — only embeddings are generated for semantic search. User-provided entities passed via `RetainContent.entities` are the sole source of entity data. Use when ingestion speed and cost matter more than structured metadata.

26
skills/hindsight-docs/references/developer/index.md
View file

@ -122,22 +122,22 @@ These settings only affect the `reflect` operation, not `recall`.
## Next Steps
### Getting Started
- [**Quick Start**](/developer/api/quickstart) — Install and get up and running in 60 seconds
- [**RAG vs Hindsight**](/developer/rag-vs-hindsight) — See how Hindsight differs from traditional RAG with real examples
- [**Quick Start**](api/quickstart.md) — Install and get up and running in 60 seconds
- [**RAG vs Hindsight**](rag-vs-hindsight.md) — See how Hindsight differs from traditional RAG with real examples
### Core Concepts
- [**Retain**](/developer/retain) — How memories are stored with multi-dimensional facts
- [**Recall**](/developer/retrieval) — How TEMPR's 4-way search retrieves memories
- [**Reflect**](/developer/reflect) — How mission, directives, and disposition shape reasoning
- [**Retain**](retain.md) — How memories are stored with multi-dimensional facts
- [**Recall**](retrieval.md) — How TEMPR's 4-way search retrieves memories
- [**Reflect**](reflect.md) — How mission, directives, and disposition shape reasoning
### API Methods
- [**Retain**](/developer/api/retain) — Store information in memory banks
- [**Recall**](/developer/api/recall) — Search and retrieve memories
- [**Reflect**](/developer/api/reflect) — Agentic reasoning with memory
- [**Mental Models**](/developer/api/mental-models) — User-curated summaries for common queries
- [**Memory Banks**](/developer/api/memory-banks) — Configure mission, directives, and disposition
- [**Documents**](/developer/api/documents) — Manage document sources
- [**Operations**](/developer/api/operations) — Monitor async tasks
- [**Retain**](api/retain.md) — Store information in memory banks
- [**Recall**](api/recall.md) — Search and retrieve memories
- [**Reflect**](api/reflect.md) — Agentic reasoning with memory
- [**Mental Models**](api/mental-models.md) — User-curated summaries for common queries
- [**Memory Banks**](api/memory-banks.md) — Configure mission, directives, and disposition
- [**Documents**](api/documents.md) — Manage document sources
- [**Operations**](api/operations.md) — Monitor async tasks
### Deployment
- [**Server Setup**](/developer/installation) — Deploy with Docker Compose, Helm, or pip
- [**Server Setup**](installation.md) — Deploy with Docker Compose, Helm, or pip

2
skills/hindsight-docs/references/developer/models.md
View file

@ -32,7 +32,7 @@ See [Configuration](./configuration#llm-provider) for setup examples.
Not sure which model to use? The **[Model Leaderboard](https://benchmarks.hindsight.vectorize.io/)** benchmarks models across accuracy, speed, cost, and reliability for retain, reflect, and observation consolidation so you can pick the right trade-off for your use case.
[![Model Leaderboard](/img/leaderboard.png)](https://benchmarks.hindsight.vectorize.io/)
[](https://benchmarks.hindsight.vectorize.io/)
### Tested Models

4
skills/hindsight-docs/references/developer/observations.md
View file

@ -120,7 +120,7 @@ observations = client.recall(
The reflect agent uses **hierarchical retrieval**:
1. **[Mental Models](/developer/api/mental-models)** — User-curated summaries (highest priority)
1. **[Mental Models](api/mental-models.md)** — User-curated summaries (highest priority)
2. **Observations** — Consolidated knowledge with freshness awareness
3. **Raw Facts** — Ground truth for verification
@ -168,7 +168,7 @@ Leave it blank to use the server default — durable, specific facts that stay t
| *"Observations are stable facts about named individuals only"* | Person-centric knowledge, tied to specific people |
| *"Observations are recurring patterns in customer support interactions"* | Failure modes, common requests, pain points |
Set `observations_mission` via the [bank config API](/developer/api/memory-banks#observations-configuration) or the [`HINDSIGHT_API_OBSERVATIONS_MISSION`](/developer/configuration#observations) environment variable.
Set `observations_mission` via the [bank config API](api/memory-banks.md#observations-configuration) or the [`HINDSIGHT_API_OBSERVATIONS_MISSION`](configuration.md#observations) environment variable.
---

10
skills/hindsight-docs/references/developer/reflect.md
View file

@ -55,11 +55,11 @@ The agent:
The agent uses a smart retrieval hierarchy:
1. **[Mental Models](/developer/api/mental-models)** — User-curated summaries you've pre-computed for common queries
2. **[Observations](/developer/observations)** — Consolidated knowledge with freshness awareness
1. **[Mental Models](api/mental-models.md)** — User-curated summaries you've pre-computed for common queries
2. **[Observations](observations.md)** — Consolidated knowledge with freshness awareness
3. **Raw Facts** — Ground truth for verification when observations are stale
**Mental models** are saved reflect responses that you create for frequently asked questions. They're checked first because they represent explicitly curated knowledge. See the [Mental Models API](/developer/api/mental-models) for how to create and manage them.
**Mental models** are saved reflect responses that you create for frequently asked questions. They're checked first because they represent explicitly curated knowledge. See the [Mental Models API](api/mental-models.md) for how to create and manage them.
If an observation is marked as **stale**, the agent automatically verifies it against current facts.
@ -132,7 +132,7 @@ The reflect mission frames how the agent reasons and responds:
- Keeps reasoning consistent across conversations
:::info Per-operation missions
The reflect mission only affects `reflect()`. To steer what gets extracted during `retain()`, use [`retain_mission`](/developer/api/memory-banks#retain-configuration). To control what gets synthesised into observations, use [`observations_mission`](/developer/api/memory-banks#observations-configuration).
The reflect mission only affects `reflect()`. To steer what gets extracted during `retain()`, use [`retain_mission`](api/memory-banks.md#retain-configuration). To control what gets synthesised into observations, use [`observations_mission`](api/memory-banks.md#observations-configuration).
---
## Disposition Shapes Reasoning
@ -187,7 +187,7 @@ Use directives for constraints that must never be violated:
:::tip
Use disposition for personality and character. Use directives for compliance and guardrails.
See [Memory Banks: Directives](/developer/api/memory-banks#directives) for how to create and manage directives.
See [Memory Banks: Directives](api/memory-banks.md#directives) for how to create and manage directives.
---

4
skills/hindsight-docs/references/developer/retain.md
View file

@ -94,7 +94,7 @@ If "Alice" appears with "Google" and "Stanford" multiple times, a new "Alice" me
You can define a controlled vocabulary of `key:value` classification labels (e.g. `pedagogy:scaffolding`, `engagement:active`) that are extracted at retain time and stored as entities. Because labels become entities, they automatically link related memories in the knowledge graph and improve both semantic and keyword retrieval. Labels can optionally also write to the memory unit's tags, enabling standard tag-based filtering during recall and reflect.
See [entity_labels in the bank config](/developer/api/memory-banks#entity-labels) for full configuration details.
See [entity_labels in the bank config](api/memory-banks.md#entity-labels) for full configuration details.
---
@ -201,7 +201,7 @@ For finer control, you can also change the **extraction mode**:
| `verbose` | When you need richer facts with full context and relationships |
| `custom` | When you want to write your own extraction rules entirely |
Set `retain_mission` and `retain_extraction_mode` via the [bank config API](/developer/api/memory-banks#retain-configuration) or the [`HINDSIGHT_API_RETAIN_MISSION`](/developer/configuration#retain) environment variable.
Set `retain_mission` and `retain_extraction_mode` via the [bank config API](api/memory-banks.md#retain-configuration) or the [`HINDSIGHT_API_RETAIN_MISSION`](configuration.md#retain) environment variable.
---

26
skills/hindsight-docs/references/faq.md
View file

@ -28,7 +28,7 @@ Hindsight is an agent memory system that provides long-term memory for AI agents
- **Supports temporal reasoning** with time-aware retrieval
- **Enables disposition-aware reflection** for nuanced reasoning
For a detailed comparison, see [RAG vs Memory](/developer/rag-vs-hindsight).
For a detailed comparison, see [RAG vs Memory](developer/rag-vs-hindsight.md).
---
@ -65,7 +65,7 @@ Unlike vector databases (just search) or RAG systems (document retrieval), Hinds
<LLMProvidersGrid />
See [Models](/developer/models) for the full list of supported providers, recommended models, and configuration examples.
See [Models](developer/models.md) for the full list of supported providers, recommended models, and configuration examples.
---
@ -73,9 +73,9 @@ See [Models](/developer/models) for the full list of supported providers, recomm
The **[Model Leaderboard](https://benchmarks.hindsight.vectorize.io/)** benchmarks models across accuracy, speed, cost, and reliability for retain, reflect, and observation consolidation — it's the best place to find the right trade-off for your use case.
[![Model Leaderboard](/img/leaderboard.png)](https://benchmarks.hindsight.vectorize.io/)
[](https://benchmarks.hindsight.vectorize.io/)
See [Models](/developer/models) for the full list of supported and tested models, provider defaults, and configuration examples.
See [Models](developer/models.md) for the full list of supported and tested models, provider defaults, and configuration examples.
---
@ -86,7 +86,7 @@ No! You have two options:
1. **Hindsight Cloud** - Fully managed service at [ui.hindsight.vectorize.io](https://ui.hindsight.vectorize.io)
2. **Self-hosted** - Deploy on your own infrastructure using Docker or direct installation
See [Installation](/developer/installation) for self-hosting instructions.
See [Installation](developer/installation.md) for self-hosting instructions.
---
@ -97,7 +97,7 @@ For running the Hindsight API server locally:
- 4GB RAM minimum (8GB recommended for production)
- LLM API key (OpenAI, Anthropic, etc.) or local LLM setup
See [Installation](/developer/installation) for setup instructions.
See [Installation](developer/installation.md) for setup instructions.
---
@ -120,7 +120,7 @@ There are two approaches for multi-user applications:
- Filter by tags during recall/reflect for per-user queries
- **Advantage**: Enables both per-user AND cross-user queries (e.g., analyze specific users or aggregate across all users)
Choose per-user banks for simplicity and privacy, or single bank with tags if you need holistic reasoning across users. See [Memory Banks](/developer/api/memory-banks) for management details.
Choose per-user banks for simplicity and privacy, or single bank with tags if you need holistic reasoning across users. See [Memory Banks](developer/api/memory-banks.md) for management details.
---
@ -132,7 +132,7 @@ Hindsight has three core operations:
- **Recall**: Search and retrieve raw memory data based on a query
- **Reflect**: Use an AI agent to answer a query using retrieved memories
See [Operations](/developer/api/operations) for API details.
See [Operations](developer/api/operations.md) for API details.
---
@ -162,7 +162,7 @@ reflect("What should I order for Alice?")
→ "I'd recommend a vegetarian sushi platter — Alice loves sushi and prefers vegetarian options." # grounded answer
```
See [Recall](/developer/api/recall) and [Reflect](/developer/reflect) for full API details.
See [Recall](developer/api/recall.md) and [Reflect](developer/reflect.md) for full API details.
---
@ -174,7 +174,7 @@ See [Recall](/developer/api/recall) and [Reflect](/developer/reflect) for full A
- Long-term behavioral patterns (e.g., "Customer is price-sensitive but values quality")
- Context for AI agent reasoning during **reflect** operations
Mental models are automatically built during retain and used by reflect to provide richer, more contextual responses. See [Mental Models](/developer/api/mental-models).
Mental models are automatically built during retain and used by reflect to provide richer, more contextual responses. See [Mental Models](developer/api/mental-models.md).
---
@ -184,7 +184,7 @@ Typical latencies:
- **Without reranking**: 50-100ms
- **With reranking**: 200-500ms (depends on reranker model and installation)
See [Performance](/developer/performance) for tuning options.
See [Performance](developer/performance.md) for tuning options.
---
@ -203,7 +203,7 @@ client.retain(bank_id="my-bank", items=[{
client.recall(bank_id="my-bank", query="...", tags=["user:alice"])
```
See [Tags](/developer/api/retain#tags-and-document_tags) for full details including document-level tagging.
See [Tags](developer/api/retain.md#tags-and-document_tags) for full details including document-level tagging.
**What about filtering by entities?**
@ -227,7 +227,7 @@ If you need explicit tag-based filtering on entity-like values, use **entity lab
client.recall(bank_id="my-bank", query="...", tags=["user:alice"])
```
See [Entity Labels](/developer/retain#entity-labels) for configuration details.
See [Entity Labels](developer/retain.md#entity-labels) for configuration details.
**What about document `metadata`?**

8512
skills/hindsight-docs/references/openapi.json Normal file
View file

File diff suppressed because it is too large Load diff

2
skills/hindsight-docs/references/sdks/cli.md
View file

@ -4,7 +4,7 @@ sidebar_position: 4
# CLI Reference
The Hindsight CLI provides command-line access to memory operations and bank management. All commands follow the [OpenAPI specification](/api-reference), so you can use `--help` on any command to see all available options.
The Hindsight CLI provides command-line access to memory operations and bank management. All commands follow the [OpenAPI specification](../openapi.json), so you can use `--help` on any command to see all available options.
## Installation

2
skills/hindsight-docs/references/sdks/embed.md
View file

@ -244,4 +244,4 @@ hindsight-embed configure
- High-availability requirements
- Multi-tenant applications
For production deployments, use the [API Service](/developer/services) with external PostgreSQL instead.
For production deployments, use the [API Service](../developer/services.md) with external PostgreSQL instead.

186
skills/hindsight-docs/references/sdks/integrations/agno.md Normal file
View file

@ -0,0 +1,186 @@
---
sidebar_position: 9
---
# Agno
Persistent memory tools for [Agno](https://github.com/agno-agi/agno) agents via Hindsight. Give your agents long-term memory with retain, recall, and reflect — using Agno's native Toolkit pattern.
## Features
- **Native Toolkit** - Extends Agno's `Toolkit` base class, just like `Mem0Tools`
- **Memory Instructions** - Pre-recall memories for injection into `Agent(instructions=[...])`
- **Three Memory Tools** - Retain (store), Recall (search), Reflect (synthesize) — include any combination
- **Flexible Bank Resolution** - Static bank ID, `RunContext.user_id`, or custom resolver
- **Simple Configuration** - Configure once globally, or pass a client directly
## Installation
```bash
pip install hindsight-agno
```
## Quick Start
```python
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from hindsight_agno import HindsightTools
agent = Agent(
model=OpenAIChat(id="gpt-4o-mini"),
tools=[HindsightTools(
bank_id="user-123",
hindsight_api_url="http://localhost:8888",
)],
)
agent.print_response("Remember that I prefer dark mode")
agent.print_response("What are my preferences?")
```
The agent now has three tools it can call:
- **`retain_memory`** — Store information to long-term memory
- **`recall_memory`** — Search long-term memory for relevant facts
- **`reflect_on_memory`** — Synthesize a reasoned answer from memories
## With Memory Instructions
Pre-recall relevant memories and inject them into the system prompt:
```python
from hindsight_agno import HindsightTools, memory_instructions
agent = Agent(
model=OpenAIChat(id="gpt-4o-mini"),
tools=[HindsightTools(
bank_id="user-123",
hindsight_api_url="http://localhost:8888",
)],
instructions=[memory_instructions(
bank_id="user-123",
hindsight_api_url="http://localhost:8888",
)],
)
```
## Selecting Tools
Include only the tools you need:
```python
tools = [HindsightTools(
bank_id="user-123",
hindsight_api_url="http://localhost:8888",
enable_retain=True,
enable_recall=True,
enable_reflect=False, # Omit reflect
)]
```
## Bank Resolution
The bank ID is resolved in order:
1. **`bank_resolver`** — Custom callable `(RunContext) -> str`
2. **`bank_id`** — Static bank ID passed to constructor
3. **`run_context.user_id`** — Automatic per-user banks
```python
# Per-user banks from RunContext
agent = Agent(
model=OpenAIChat(id="gpt-4o-mini"),
tools=[HindsightTools(hindsight_api_url="http://localhost:8888")],
user_id="user-123", # Used as bank_id
)
# Custom resolver
def resolve_bank(ctx):
return f"team-{ctx.user_id}"
agent = Agent(
model=OpenAIChat(id="gpt-4o-mini"),
tools=[HindsightTools(
bank_resolver=resolve_bank,
hindsight_api_url="http://localhost:8888",
)],
)
```
## Global Configuration
Instead of passing connection details to every toolkit, configure once:
```python
from hindsight_agno import configure, HindsightTools
configure(
hindsight_api_url="http://localhost:8888",
api_key="your-api-key", # Or set HINDSIGHT_API_KEY env var
budget="mid", # Recall budget: low/mid/high
max_tokens=4096, # Max tokens for recall results
tags=["env:prod"], # Tags for stored memories
recall_tags=["scope:global"], # Tags to filter recall
recall_tags_match="any", # Tag match mode: any/all/any_strict/all_strict
)
# Now create toolkit without passing connection details
tools = [HindsightTools(bank_id="user-123")]
```
## Configuration Reference
### `HindsightTools()`
| Parameter | Default | Description |
|---|---|---|
| `bank_id` | `None` | Static Hindsight memory bank ID |
| `bank_resolver` | `None` | Callable `(RunContext) -> str` for dynamic bank ID |
| `client` | `None` | Pre-configured Hindsight client |
| `hindsight_api_url` | `None` | API URL (used if no client provided) |
| `api_key` | `None` | API key (used if no client provided) |
| `budget` | `"mid"` | Recall/reflect budget level (low/mid/high) |
| `max_tokens` | `4096` | Maximum tokens for recall results |
| `tags` | `None` | Tags applied when storing memories |
| `recall_tags` | `None` | Tags to filter when searching |
| `recall_tags_match` | `"any"` | Tag matching mode |
| `enable_retain` | `True` | Include the retain (store) tool |
| `enable_recall` | `True` | Include the recall (search) tool |
| `enable_reflect` | `True` | Include the reflect (synthesize) tool |
### `memory_instructions()`
| Parameter | Default | Description |
|---|---|---|
| `bank_id` | *required* | Hindsight memory bank ID |
| `client` | `None` | Pre-configured Hindsight client |
| `hindsight_api_url` | `None` | API URL (used if no client provided) |
| `api_key` | `None` | API key (used if no client provided) |
| `query` | `"relevant context about the user"` | Recall query for memory injection |
| `budget` | `"low"` | Recall budget level |
| `max_results` | `5` | Maximum memories to inject |
| `max_tokens` | `4096` | Maximum tokens for recall results |
| `prefix` | `"Relevant memories:\n"` | Text prepended before memory list |
| `tags` | `None` | Tags to filter recall results |
| `tags_match` | `"any"` | Tag matching mode |
### `configure()`
| Parameter | Default | Description |
|---|---|---|
| `hindsight_api_url` | Production API | Hindsight API URL |
| `api_key` | `HINDSIGHT_API_KEY` env | API key for authentication |
| `budget` | `"mid"` | Default recall budget level |
| `max_tokens` | `4096` | Default max tokens for recall |
| `tags` | `None` | Default tags for retain operations |
| `recall_tags` | `None` | Default tags to filter recall |
| `recall_tags_match` | `"any"` | Default tag matching mode |
| `verbose` | `False` | Enable verbose logging |
## Requirements
- Python >= 3.10
- agno
- hindsight-client >= 0.4.0
- A running Hindsight API server

219
skills/hindsight-docs/references/sdks/integrations/hermes.md Normal file
View file

@ -0,0 +1,219 @@
---
sidebar_position: 10
---
# Hermes Agent
Hindsight memory integration for [Hermes Agent](https://github.com/NousResearch/hermes-agent). Gives your Hermes agent persistent long-term memory via retain, recall, and reflect tools.
## What it does
This package registers three tools into Hermes via its plugin system:
- **`hindsight_retain`** — Stores information to long-term memory. Hermes calls this when the user shares facts, preferences, or anything worth remembering.
- **`hindsight_recall`** — Searches long-term memory for relevant information. Returns a numbered list of matching memories.
- **`hindsight_reflect`** — Synthesizes a thoughtful answer from stored memories. Use this when you want Hermes to reason over what it knows rather than return raw facts.
These tools appear under the `[hindsight]` toolset in Hermes's `/tools` list.
## Setup
### 1. Install hindsight-hermes into the Hermes venv
The package must be installed in the **same Python environment** that Hermes runs in, so the entry point is discoverable.
```bash
uv pip install hindsight-hermes --python $HOME/.hermes/hermes-agent/venv/bin/python
```
### 2. Set environment variables
The plugin reads its configuration from environment variables. Set these before launching Hermes:
```bash
# Required — tells the plugin where Hindsight is running
export HINDSIGHT_API_URL=http://localhost:8888
# Required — the memory bank to read/write. Think of this as a "brain" for one user or agent.
export HINDSIGHT_BANK_ID=my-agent
# Optional — only needed if using Hindsight Cloud (https://api.hindsight.vectorize.io)
export HINDSIGHT_API_KEY=your-api-key
# Optional — recall budget: low (fast), mid (default), high (thorough)
export HINDSIGHT_BUDGET=mid
```
If neither `HINDSIGHT_API_URL` nor `HINDSIGHT_API_KEY` is set, the plugin silently skips registration — Hermes starts normally without the Hindsight tools.
### 3. Disable Hermes's built-in memory tool
Hermes has its own `memory` tool that saves to local files (`~/.hermes/`). If both are active, the LLM tends to prefer the built-in one since it's familiar. Disable it so the LLM uses Hindsight instead:
```bash
hermes tools disable memory
```
This persists across sessions. You can re-enable it later with `hermes tools enable memory`.
### 4. Start Hindsight API
Follow the [Quick Start](../../developer/api/quickstart.md) guide to get the Hindsight API running, then come back here.
### 5. Launch Hermes
```bash
hermes
```
Verify the plugin loaded by typing `/tools` — you should see:
```
[hindsight]
* hindsight_recall - Search long-term memory for relevant information.
* hindsight_reflect - Synthesize a thoughtful answer from long-term memories.
* hindsight_retain - Store information to long-term memory for later retrieval.
```
### 6. Test it
**Store a memory:**
> Remember that my favourite colour is red
You should see `⚡ hindsight` in the response, confirming it called `hindsight_retain`.
**Recall a memory:**
> What's my favourite colour?
**Reflect on memories:**
> Based on what you know about me, suggest a colour scheme for my IDE
This calls `hindsight_reflect`, which synthesizes a response from all stored memories.
**Verify via API:**
```bash
curl -s http://localhost:8888/v1/default/banks/my-agent/memories/recall \
-H "Content-Type: application/json" \
-d '{"query": "favourite colour", "budget": "low"}' | python3 -m json.tool
```
## Troubleshooting
### Tools don't appear in `/tools`
1. **Check the plugin is installed in the right venv.** Run this from the Hermes venv:
```bash
python -c "from hindsight_hermes import register; print('OK')"
```
2. **Check the entry point is registered:**
```bash
python -c "
import importlib.metadata
eps = importlib.metadata.entry_points(group='hermes_agent.plugins')
print(list(eps))
"
```
You should see `EntryPoint(name='hindsight', value='hindsight_hermes', group='hermes_agent.plugins')`.
3. **Check env vars are set.** The plugin skips registration silently if `HINDSIGHT_API_URL` and `HINDSIGHT_API_KEY` are both unset.
### Hermes uses built-in memory instead of Hindsight
Run `hermes tools disable memory` and restart. The built-in `memory` tool and Hindsight tools have overlapping purposes — the LLM will prefer whichever it's more familiar with, which is usually the built-in one.
### Bank not found errors
The plugin auto-creates banks on first use. If you see bank errors, check that the Hindsight API is running and `HINDSIGHT_API_URL` is correct.
### Connection refused
Make sure the Hindsight API is running and listening on the URL you configured. Test with:
```bash
curl http://localhost:8888/health
```
## Manual registration (advanced)
If you don't want to use the plugin system, you can register tools directly in a Hermes startup script or custom agent:
```python
from hindsight_hermes import register_tools
register_tools(
bank_id="my-agent",
hindsight_api_url="http://localhost:8888",
budget="mid",
tags=["hermes"], # applied to all retained memories
recall_tags=["hermes"], # filter recall to only these tags
)
```
This imports `tools.registry` from Hermes at call time and registers the three tools directly. This approach gives you more control over parameters but requires Hermes to be importable.
## Memory instructions (system prompt injection)
Pre-recall memories at startup and inject them into the system prompt, so the agent starts every conversation with relevant context:
```python
from hindsight_hermes import memory_instructions
context = memory_instructions(
bank_id="my-agent",
hindsight_api_url="http://localhost:8888",
query="user preferences and important context",
budget="low",
max_results=5,
)
# Returns:
# Relevant memories:
# 1. User's favourite colour is red
# 2. User prefers dark mode
```
This never raises — if the API is down or no memories exist, it returns an empty string.
## Global configuration (advanced)
Instead of passing parameters to every call, configure once:
```python
from hindsight_hermes import configure
configure(
hindsight_api_url="http://localhost:8888",
api_key="your-key",
budget="mid",
tags=["hermes"],
)
```
Subsequent calls to `register_tools()` or `memory_instructions()` will use these defaults if no explicit values are provided.
## MCP alternative
Hermes also supports MCP servers natively. You can use Hindsight's MCP server directly instead of this plugin — no `hindsight-hermes` package needed:
```yaml
# In your Hermes config
mcp_servers:
- name: hindsight
url: http://localhost:8888/mcp
```
This exposes the same retain/recall/reflect operations through Hermes's MCP integration. The tradeoff is that MCP tools may have different naming and the LLM needs to discover them, whereas the plugin registers tools with Hermes-native schemas.
## Configuration reference
| Parameter | Env Var | Default | Description |
|-----------|---------|---------|-------------|
| `hindsight_api_url` | `HINDSIGHT_API_URL` | `https://api.hindsight.vectorize.io` | Hindsight API URL |
| `api_key` | `HINDSIGHT_API_KEY` | — | API key for authentication |
| `bank_id` | `HINDSIGHT_BANK_ID` | — | Memory bank ID |
| `budget` | `HINDSIGHT_BUDGET` | `mid` | Recall budget (low/mid/high) |
| `max_tokens` | — | `4096` | Max tokens for recall results |
| `tags` | — | — | Tags applied when storing memories |
| `recall_tags` | — | — | Tags to filter recall results |
| `recall_tags_match` | — | `any` | Tag matching mode (any/all/any_strict/all_strict) |
| `toolset` | — | `hindsight` | Hermes toolset group name |

4
skills/hindsight-docs/references/sdks/integrations/local-mcp.md
View file

@ -132,11 +132,11 @@ The local server exposes the full tool set (29 tools in multi-bank mode, 26 in s
| `list_banks` | List all memory banks (multi-bank only) |
| `create_bank` | Create or configure a memory bank (multi-bank only) |
For detailed parameter documentation, see the [MCP Server reference](/developer/mcp-server#available-tools).
For detailed parameter documentation, see the [MCP Server reference](../../developer/mcp-server.md#available-tools).
## Environment Variables
All standard [Hindsight configuration variables](/developer/configuration) are supported. Key ones for local use:
All standard [Hindsight configuration variables](../../developer/configuration.md) are supported. Key ones for local use:
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|