Skip to content

Commit 7b671f0

Browse files
benfrank241benfrank241
authored
docs(guides): add framework memory guides batch (#1432)
1 parent 0b0f417 commit 7b671f0

20 files changed

Lines changed: 1205 additions & 0 deletions

‎hindsight-docs/guides/2026-05-04-guide-agentcore-memory-with-hindsight.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: "Guide: Add AgentCore Runtime Memory with Hindsight"
3+
authors: [benfrank241]
4+
date: 2026-05-04T15:00:00Z
5+
tags: [how-to, agentcore, bedrock, memory]
6+
description: "Add AgentCore Runtime memory with Hindsight using the runtime adapter, stable user bank IDs, and recall plus retain hooks across session churn."
7+
image: /img/guides/guide-agentcore-memory-with-hindsight.png
8+
hide_table_of_contents: true
9+
---
10+
11+
![Guide: Add AgentCore Runtime Memory with Hindsight](/img/guides/guide-agentcore-memory-with-hindsight.png)
12+
13+
If you want **AgentCore Runtime memory with Hindsight**, the cleanest pattern is to wrap your Bedrock AgentCore handler with `HindsightRuntimeAdapter` and key memory to a stable user identity instead of the ephemeral runtime session ID. That gives AgentCore durable memory across session churn, which is the main gap teams hit when they move from demos to real user traffic.
14+
15+
This matters because AgentCore Runtime sessions are intentionally short lived. Without an external memory layer, the agent can keep losing context whenever the runtime environment turns over.
16+
17+
If you want the underlying reference open while you work, keep [the AgentCore Runtime integration docs](https://hindsight.vectorize.io/docs/integrations/agentcore), [the docs home](https://hindsight.vectorize.io/docs), [the quickstart guide](https://hindsight.vectorize.io/docs/quickstart), [Hindsight's recall API](https://hindsight.vectorize.io/docs/api/recall), and [Hindsight's retain API](https://hindsight.vectorize.io/docs/api/retain) nearby.
18+
19+
<!-- truncate -->
20+
21+
> **Quick answer**
22+
>
23+
> 1. Install the AgentCore Runtime integration or plugin.
24+
> 2. Point it at Hindsight Cloud or a local Hindsight API.
25+
> 3. Wire memory into your AgentCore Runtime runtime with a stable bank ID.
26+
> 4. Store one preference or project fact, then start a fresh run.
27+
> 5. Confirm that recall brings the earlier context back automatically.
28+
29+
## Why this setup works
30+
31+
The runtime adapter gives you a clean recall, execute, retain loop around each turn. `before_turn()` fetches context, `run_turn()` wraps the whole exchange, and `after_turn()` stores the result. The critical design rule is simple: bank IDs must track stable user identity, not `runtimeSessionId`.
32+
33+
## Prerequisites
34+
35+
- An AgentCore Runtime handler that already receives a trusted user identifier
36+
- Python and `hindsight-agentcore` installed
37+
- A stable bank pattern, usually tenant plus user plus agent name
38+
39+
## Step 1: Install the integration
40+
41+
```bash
42+
pip install hindsight-agentcore
43+
```
44+
45+
## Step 2: Connect AgentCore Runtime to Hindsight
46+
47+
```python
48+
import os
49+
from hindsight_agentcore import configure
50+
51+
configure(
52+
hindsight_api_url="https://api.hindsight.vectorize.io",
53+
api_key=os.environ["HINDSIGHT_API_KEY"],
54+
)
55+
```
56+
57+
## Step 3: Wire memory into your runtime
58+
59+
```python
60+
from hindsight_agentcore import HindsightRuntimeAdapter, TurnContext
61+
62+
adapter = HindsightRuntimeAdapter(agent_name="support-agent")
63+
64+
async def handler(event: dict) -> dict:
65+
context = TurnContext(
66+
runtime_session_id=event["sessionId"],
67+
user_id=event["userId"],
68+
agent_name="support-agent",
69+
tenant_id=event.get("tenantId"),
70+
request_id=event.get("requestId"),
71+
)
72+
73+
result = await adapter.run_turn(
74+
context=context,
75+
payload={"prompt": event["prompt"]},
76+
agent_callable=run_my_agent,
77+
)
78+
return result
79+
```
80+
81+
The default bank format follows `tenant:{tenant_id}:user:{user_id}:agent:{agent_name}`. That is exactly what you want for durable memory across Runtime session churn.
82+
83+
## Step 4: Choose the right bank strategy
84+
85+
Do not key memory to `runtimeSessionId`. That ID is ephemeral and will fragment memory immediately. Use a stable identity that survives across sessions, such as tenant plus user plus agent name. If several agent personas share the same account, give each persona its own suffix so memory stays coherent.
86+
87+
## Step 5: Verify that memory is working
88+
89+
1. Run one turn for a test user and store a preference or account detail.
90+
2. Trigger another Runtime session for the same user.
91+
3. Ask for the earlier detail and confirm that the adapter recalls it before the agent answers.
92+
4. Repeat the test for a second user to confirm that banks stay isolated.
93+
94+
If the second run can answer with details from the first run, your setup is working. If it cannot, turn on debug logging, check the configured bank ID, and confirm that the retain call actually completed.
95+
96+
## Common mistakes
97+
98+
- Using a client supplied identifier that is not trusted, which can mix memory between users
99+
- Keying the bank to `runtimeSessionId`, which breaks continuity by design
100+
- Turning on reflect everywhere when recall would be faster and simpler for most turns
101+
102+
## FAQ
103+
104+
### Why should I avoid runtimeSessionId for memory?
105+
106+
Because AgentCore Runtime sessions are ephemeral. A memory bank tied to that ID dies with the session pattern you are trying to outgrow.
107+
108+
### When should I use reflect mode?
109+
110+
Use reflect selectively for harder reasoning steps. Keep normal turns on recall mode for lower latency.
111+
112+
### Can retention run in the background?
113+
114+
Yes. The integration supports async retention so user turns do not have to wait for retain to finish.
115+
116+
## Next Steps
117+
118+
- Start with [Hindsight Cloud](https://hindsight.vectorize.io) if you want a hosted memory backend
119+
- Read [the full Hindsight docs](https://hindsight.vectorize.io/docs)
120+
- Follow [the quickstart guide](https://hindsight.vectorize.io/docs/quickstart)
121+
- Review [Hindsight's recall API](https://hindsight.vectorize.io/docs/api/recall)
122+
- Review [Hindsight's retain API](https://hindsight.vectorize.io/docs/api/retain)
123+
- Compare a related workflow in [Agno persistent memory](https://hindsight.vectorize.io/blog/agno-persistent-memory)

‎hindsight-docs/guides/2026-05-04-guide-claude-code-memory-with-hindsight.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
---
2+
title: "Guide: Add Claude Code Persistent Memory with Hindsight"
3+
authors: [benfrank241]
4+
date: 2026-05-04T15:00:00Z
5+
tags: [how-to, claude-code, coding-agents, memory]
6+
description: "Add Claude Code persistent memory with Hindsight using the memory plugin, automatic recall hooks, and project aware bank IDs across sessions."
7+
image: /img/guides/guide-claude-code-memory-with-hindsight.png
8+
hide_table_of_contents: true
9+
---
10+
11+
![Guide: Add Claude Code Persistent Memory with Hindsight](/img/guides/guide-claude-code-memory-with-hindsight.png)
12+
13+
If you want **Claude Code persistent memory with Hindsight**, the cleanest setup is to install the Hindsight memory plugin, connect it to Hindsight Cloud or a local daemon, and let the built in hooks handle recall and retain automatically. That gives Claude Code continuity across sessions instead of forcing every new run to rediscover your project conventions, preferences, or earlier decisions.
14+
15+
The plugin is a strong fit for coding work because it wires memory directly into Claude Code's session lifecycle. Recall runs before prompts, retain runs after responses, and dynamic bank IDs let you decide whether memory should be shared across projects or isolated per repo.
16+
17+
If you want the underlying reference open while you work, keep [the Claude Code integration docs](https://hindsight.vectorize.io/docs/integrations/claude-code), [the docs home](https://hindsight.vectorize.io/docs), [the quickstart guide](https://hindsight.vectorize.io/docs/quickstart), [Hindsight's recall API](https://hindsight.vectorize.io/docs/api/recall), and [Hindsight's retain API](https://hindsight.vectorize.io/docs/api/retain) nearby.
18+
19+
<!-- truncate -->
20+
21+
> **Quick answer**
22+
>
23+
> 1. Install the Claude Code integration or plugin.
24+
> 2. Point it at Hindsight Cloud or a local Hindsight API.
25+
> 3. Wire memory into your Claude Code runtime with a stable bank ID.
26+
> 4. Store one preference or project fact, then start a fresh run.
27+
> 5. Confirm that recall brings the earlier context back automatically.
28+
29+
## Why this setup works
30+
31+
The Claude Code plugin uses hook events that already exist in the runtime. `UserPromptSubmit` injects recalled memories as additional context, `Stop` retains the new conversation content, and `SessionStart` can warm up the Hindsight side early so recall is ready when you need it. You do not need to teach the model to remember manually, because the integration handles the memory loop for you.
32+
33+
## Prerequisites
34+
35+
- Claude Code installed and the plugin marketplace available
36+
- A reachable Hindsight backend, either [Hindsight Cloud](https://hindsight.vectorize.io) or a local daemon
37+
- One decision about memory scope, shared across all work or isolated per project
38+
39+
## Step 1: Install the integration
40+
41+
```bash
42+
claude plugin marketplace add vectorize-io/hindsight
43+
claude plugin install hindsight-memory
44+
```
45+
46+
## Step 2: Connect Claude Code to Hindsight
47+
48+
```json
49+
{
50+
"hindsightApiUrl": "https://api.hindsight.vectorize.io",
51+
"hindsightApiToken": "your-api-key"
52+
}
53+
```
54+
55+
Save that as `~/.hindsight/claude-code.json`. If you prefer a local daemon, leave `hindsightApiUrl` empty and export an LLM provider key before launching Claude Code. For example:
56+
57+
```bash
58+
export OPENAI_API_KEY="sk-your-key"
59+
claude
60+
```
61+
62+
## Step 3: Wire memory into your runtime
63+
64+
```json
65+
{
66+
"dynamicBankId": true,
67+
"dynamicBankGranularity": ["agent", "project"],
68+
"agentName": "claude-code",
69+
"autoRecall": true,
70+
"autoRetain": true,
71+
"recallBudget": "mid"
72+
}
73+
```
74+
75+
With that config, the plugin derives a bank per project while still using the same Claude Code agent identity. If you want one shared bank for everything, set `dynamicBankId` to `false` and provide a fixed `bankId` instead.
76+
77+
## Step 4: Choose the right bank strategy
78+
79+
Use a static bank when you want one long running memory for all Claude Code work, for example a personal coding assistant that should remember preferences everywhere. Use dynamic bank IDs when each repo should stay isolated. The default project based pattern is usually the safer choice because it prevents unrelated codebases from polluting each other.
80+
81+
## Step 5: Verify that memory is working
82+
83+
1. Start a Claude Code session and tell it one fact that should be remembered, such as your preferred test command or branch naming rule.
84+
2. End the session, then start a fresh session in the same project.
85+
3. Ask Claude Code what it remembers about the project setup or your preferred workflow.
86+
4. If needed, enable debug logging and confirm the same bank ID was used for both runs.
87+
88+
If the second run can answer with details from the first run, your setup is working. If it cannot, turn on debug logging, check the configured bank ID, and confirm that the retain call actually completed.
89+
90+
## Common mistakes
91+
92+
- Installing the plugin but never creating `~/.hindsight/claude-code.json`, so the plugin has nowhere to connect
93+
- Using one static bank across unrelated repos, which makes memory feel noisy instead of useful
94+
- Running local daemon mode without an LLM provider configured, which prevents retain from completing
95+
96+
## FAQ
97+
98+
### Do users see the recalled memory block in the transcript?
99+
100+
No. The plugin injects recalled memories as additional context for Claude Code, not as visible chat text.
101+
102+
### Should I use Hindsight Cloud or a local daemon?
103+
104+
Cloud is the fastest way to get started. A local daemon is useful when you want a local first setup or tighter control over the backend.
105+
106+
### Can I keep memory separate per repo?
107+
108+
Yes. Turn on `dynamicBankId` and include `project` in `dynamicBankGranularity` so each repo gets its own bank.
109+
110+
## Next Steps
111+
112+
- Start with [Hindsight Cloud](https://hindsight.vectorize.io) if you want a hosted memory backend
113+
- Read [the full Hindsight docs](https://hindsight.vectorize.io/docs)
114+
- Follow [the quickstart guide](https://hindsight.vectorize.io/docs/quickstart)
115+
- Review [Hindsight's recall API](https://hindsight.vectorize.io/docs/api/recall)
116+
- Review [Hindsight's retain API](https://hindsight.vectorize.io/docs/api/retain)
117+
- Compare a related workflow in [Adding Memory to Codex with Hindsight](https://hindsight.vectorize.io/blog/adding-memory-to-codex-with-hindsight)

‎hindsight-docs/guides/2026-05-04-guide-codex-memory-with-hindsight.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
title: "Guide: Add Codex CLI Persistent Memory with Hindsight"
3+
authors: [benfrank241]
4+
date: 2026-05-04T15:00:00Z
5+
tags: [how-to, codex, coding-agents, memory]
6+
description: "Add Codex CLI persistent memory with Hindsight using hook based recall, automatic retain, and project scoped bank IDs that survive across sessions."
7+
image: /img/guides/guide-codex-memory-with-hindsight.png
8+
hide_table_of_contents: true
9+
---
10+
11+
![Guide: Add Codex CLI Persistent Memory with Hindsight](/img/guides/guide-codex-memory-with-hindsight.png)
12+
13+
If you want **Codex CLI persistent memory with Hindsight**, the fastest path is to install the Hindsight hook bundle, point Codex at Hindsight Cloud or a local daemon, and let the session hooks handle recall and retain automatically. That gives Codex continuity across coding sessions without making you re explain the same repo habits and project context every time.
14+
15+
This pattern works especially well for project based development. Codex already exposes session hooks, so Hindsight can recall relevant context before each prompt and retain the finished turn after each response.
16+
17+
If you want the underlying reference open while you work, keep [the docs home](https://hindsight.vectorize.io/docs), [the quickstart guide](https://hindsight.vectorize.io/docs/quickstart), [Hindsight's recall API](https://hindsight.vectorize.io/docs/api/recall), and [Hindsight's retain API](https://hindsight.vectorize.io/docs/api/retain) nearby.
18+
19+
<!-- truncate -->
20+
21+
> **Quick answer**
22+
>
23+
> 1. Install the Codex CLI integration or plugin.
24+
> 2. Point it at Hindsight Cloud or a local Hindsight API.
25+
> 3. Wire memory into your Codex CLI runtime with a stable bank ID.
26+
> 4. Store one preference or project fact, then start a fresh run.
27+
> 5. Confirm that recall brings the earlier context back automatically.
28+
29+
## Why this setup works
30+
31+
Codex CLI exposes exactly the lifecycle points a memory system needs. `SessionStart` can warm the server, `UserPromptSubmit` can inject recalled context, and `Stop` can retain the conversation. That means you get automatic memory without adding manual retain calls to every workflow.
32+
33+
## Prerequisites
34+
35+
- OpenAI Codex CLI version 0.116.0 or later
36+
- Python 3.9 or later for the hook scripts
37+
- A reachable Hindsight backend and one decision about whether memory should be shared or project scoped
38+
39+
## Step 1: Install the integration
40+
41+
```bash
42+
curl -fsSL https://hindsight.vectorize.io/get-codex | bash
43+
```
44+
45+
The installer places the hook scripts under `~/.hindsight/codex/scripts/`, writes `~/.codex/hooks.json`, and enables hook support in `~/.codex/config.toml`.
46+
47+
## Step 2: Connect Codex CLI to Hindsight
48+
49+
```json
50+
{
51+
"hindsightApiUrl": "https://api.hindsight.vectorize.io",
52+
"hindsightApiToken": "your-api-key",
53+
"bankId": "my-codex-memory"
54+
}
55+
```
56+
57+
Save that as `~/.hindsight/codex.json`. For local daemon mode, you can leave `hindsightApiUrl` empty and export a provider key before starting Codex:
58+
59+
```bash
60+
export OPENAI_API_KEY=sk-your-key
61+
codex
62+
```
63+
64+
## Step 3: Wire memory into your runtime
65+
66+
```json
67+
{
68+
"dynamicBankId": true,
69+
"dynamicBankGranularity": ["agent", "project"],
70+
"autoRecall": true,
71+
"autoRetain": true,
72+
"retainEveryNTurns": 10,
73+
"recallBudget": "mid"
74+
}
75+
```
76+
77+
That configuration keeps memory separate per project. If you want one shared bank for everything, set `dynamicBankId` to `false` and keep a single `bankId`.
78+
79+
## Step 4: Choose the right bank strategy
80+
81+
For Codex, project scoped banks are usually the right default. They stop unrelated repositories from leaking into each other while still giving you continuity for the same codebase. A shared bank only makes sense when the same conventions should follow you everywhere, such as global shell preferences or personal coding habits.
82+
83+
## Step 5: Verify that memory is working
84+
85+
1. Use Codex in one repo and store a fact such as the preferred lint command or release process.
86+
2. End the session and start a new Codex session in the same repo.
87+
3. Ask Codex to recall the repo preference you stored earlier.
88+
4. If recall misses, confirm that hooks are enabled and that both runs used the same derived bank ID.
89+
90+
If the second run can answer with details from the first run, your setup is working. If it cannot, turn on debug logging, check the configured bank ID, and confirm that the retain call actually completed.
91+
92+
## Common mistakes
93+
94+
- Installing the hook bundle on an older Codex version that does not support hooks
95+
- Forgetting to turn on `codex_hooks = true` in `~/.codex/config.toml`
96+
- Keeping `dynamicBankId` off when you expected memory isolation per project
97+
98+
## FAQ
99+
100+
### Does this work with Hindsight Cloud?
101+
102+
Yes. Set `hindsightApiUrl` to `https://api.hindsight.vectorize.io` and provide your token in `~/.hindsight/codex.json`.
103+
104+
### Can I use a local server instead?
105+
106+
Yes. Leave `hindsightApiUrl` empty and let the hooks connect to a local Hindsight daemon.
107+
108+
### How do I debug missing memories?
109+
110+
Turn on `debug`, check stderr output, and confirm that the same bank ID is used when Codex retains and recalls.
111+
112+
## Next Steps
113+
114+
- Start with [Hindsight Cloud](https://hindsight.vectorize.io) if you want a hosted memory backend
115+
- Read [the full Hindsight docs](https://hindsight.vectorize.io/docs)
116+
- Follow [the quickstart guide](https://hindsight.vectorize.io/docs/quickstart)
117+
- Review [Hindsight's recall API](https://hindsight.vectorize.io/docs/api/recall)
118+
- Review [Hindsight's retain API](https://hindsight.vectorize.io/docs/api/retain)
119+
- Compare a related workflow in [Adding Memory to Codex with Hindsight](https://hindsight.vectorize.io/blog/adding-memory-to-codex-with-hindsight)

0 commit comments

Comments
 (0)