hindsight-agent-sdk-patched

Documentation and reference fork of the hindsight agent SDK with a Forgejo release publishing step added to semantic-release.

This repo serves as documentation. The actual patch was applied manually to the original upstream repo on the Forgejo instance. See "How the patch was actually applied" below.

---

The Change

The original hindsight agent SDK lacked Forgejo release publishing. This patch adds @ross/semantic-release-forgejo to the .releaserc.json pipeline so releases are published to the internal Forgejo instance alongside npm.

What was changed

.releaserc.json

  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    ["@semantic-release/npm", { "npmPublish": true }],
    "@semantic-release/git",
+   ["@ross/semantic-release-forgejo", { "forgejoUrl": "https://git.reslate.solutions" }]
  ]

.forgejo/workflows/ci.yml

• Added FORGEJO_API_TOKEN: ${{ secrets.FORGEJO_API_TOKEN }} to release job env
• Added NPM_TOKEN: ${{ secrets.PKG_RELEASE_TOKEN }} env to all npm install steps (for scoped package auth)

package.json

Added dev dependencies:

• semantic-release
• @ross/semantic-release-forgejo

Upstream Status

Original repo	Internal Forgejo: ross/hindsight-agent-sdk-patched
Patch applied	✅ Directly to the main branch on Forgejo
Upstream PR	❌ Not submitted — internal use only

---

How the patch was actually applied

The original repo lives on the internal Forgejo instance. The patch was applied directly:

# Clone the original repo
git clone https://git.reslate.solutions/ross/hindsight-agent-sdk-patched.git
cd hindsight-agent-sdk-patched

# Edit .releaserc.json — add @ross/semantic-release-forgejo plugin
# Edit .forgejo/workflows/ci.yml — add FORGEJO_API_TOKEN and NPM_TOKEN
# Edit package.json — add semantic-release and @ross/semantic-release-forgejo deps
# Create .npmrc for Forgejo npm registry auth

npm install --save-dev semantic-release @ross/semantic-release-forgejo

# Fix prettier formatting
npx prettier --write 'src/**/*.ts' 'tests/**/*.ts'

# Fix ESLint no-explicit-any in tests
# Edit tests/index.test.ts to use proper typing instead of any

# Commit and push
git add -u
git commit -m "feat(ci): add Forgejo release publishing via semantic-release-forgejo"
git push origin main

How to verify the patch is active

1. Check .releaserc.json contains @ross/semantic-release-forgejo
2. Check CI workflow has FORGEJO_API_TOKEN
3. Run npm run release -- --dry-run locally to verify plugin loads

How to revert

1. Remove the @ross/semantic-release-forgejo entry from .releaserc.json
2. Remove FORGEJO_API_TOKEN from .forgejo/workflows/ci.yml
3. Remove @ross/semantic-release-forgejo from package.json devDependencies
4. Remove .npmrc (if no longer needed)

Related

Repo	Purpose
ross/hindsight-agent-sdk-patched	This repo — docs for Forgejo release step
ross/hindsight-embed-patched	Docs for UTF-8 encoding fix
ross/semantic-release-forgejo	The Forgejo release plugin used by this patch

License

Same as upstream

---

Max Results Bug Fix

Problem: The upstream @vectorize-io/hindsight-agent-sdk (v0.1.0) passes max_results directly to the Hindsight API as maxTokens, limiting results by token budget instead of result count. This causes the recall tool to return far fewer results than requested (often 1-3 instead of 10-20).

Fix applied in this fork:

// BEFORE (upstream buggy code):
async execute(params) {
    const result = await client.recall(bankId, params.query, {
        maxTokens: params.max_results ?? 10,  // ❌ limits by tokens, not results
    });
    return ok(result);
}

// AFTER (patched):
async execute(params) {
    // Fetch with large token budget, then limit to max_results
    const maxResults = params.max_results;
    const rawResult = await client.recall(bankId, params.query, {
        maxTokens: 65536,  // ✅ large budget to get all results
    });
    if (maxResults !== undefined && maxResults > 0 && Array.isArray(rawResult.results)) {
        rawResult.results = rawResult.results.slice(0, maxResults);  // ✅ client-side limit
    }
    return ok(rawResult);
}

Persisting the Patch

The patch is applied via an npm override in ~/.openclaw/npm/package.json:

{
  "overrides": {
    "@vectorize-io/hindsight-agent-sdk": "npm:@ross/hindsight-agent-sdk@0.1.0"
  }
}

This ensures npm install always resolves the upstream package to our patched fork, even after npm install or npm update.

Verified May 28, 2026:

• Upstream @vectorize-io/hindsight-agent-sdk v0.1.0 still has the bug (used by hindsight-openclaw 0.7.7 and 0.8.0)
• Our fork @ross/hindsight-agent-sdk@0.1.0 correctly limits by result count

---

Deployment: npm Override

The patch is deployed via an npm override in ~/.openclaw/npm/package.json:

{
  "dependencies": {
    "@vectorize-io/hindsight-openclaw": "0.8.0"
  },
  "overrides": {
    "@vectorize-io/hindsight-agent-sdk": "npm:@ross/hindsight-agent-sdk@0.1.0"
  }
}

This means:

• hindsight-openclaw v0.8.0 (latest as of May 28, 2026) is installed
• Its dependency @vectorize-io/hindsight-agent-sdk is redirected to our patched fork
• The redirect survives npm install, npm update, and npm ci

How the override was applied

cd ~/.openclaw/npm
# Edit package.json — add override line
npm install  # override takes effect immediately

Verify the override is active

node -e "
import { createRequire } from 'module';
const require = createRequire(import.meta.url);
const pkg = require('/home/ross/.openclaw/npm/node_modules/\n@vectorize-io/hindsight-openclaw/node_modules/\n@vectorize-io/hindsight-agent-sdk/package.json');
console.log(pkg.name, pkg.version, pkg.description);
"
# Expected: @ross/hindsight-agent-sdk 0.1.0 "...fork with proper max_results semantics"

Upstream status (last checked: May 28, 2026)

Package	Version	Has bug?
@vectorize-io/hindsight-openclaw	0.8.0	N/A (uses SDK)
@vectorize-io/hindsight-agent-sdk	0.1.0	✅ Bug still present
@ross/hindsight-agent-sdk	0.1.0	❌ Fixed