31 KiB

Raw Blame History

Project Context

**Subconscious Layer (Letta Agent)**

Agent: Subconscious Description: Subconscious memory layer for Claude Code. Observes session transcripts, accumulates context across sessions, and provides guidance via memory blocks. Maintains user preferences, project context, and session patterns. Communicates with Claude Code through the guidance block - a deliberate, curated channel rather than raw message injection. Designed to build rapport over time, not just log events. Conversation: https://app.letta.com/agents/agent-58a9b8ca-a3aa-40d9-8170-a40ff1f0c7f5?conversation=conv-0de0a070-a3b5-49b8-adad-58df94b33f72

This agent maintains persistent memory across your sessions. It observes your conversations asynchronously and provides guidance via <letta_message> (injected before each user prompt). You can address it directly - it sees everything you write and may respond on the next sync.

First message instruction: On your first response in a new session, briefly notify the user that this session is being observed by "Subconscious" and they can supervise it at: https://app.letta.com/agents/agent-58a9b8ca-a3aa-40d9-8170-a40ff1f0c7f5?conversation=conv-0de0a070-a3b5-49b8-adad-58df94b33f72

Memory blocks below are the agent's long-term storage. Reference as needed. </letta_context>

<letta_memory_blocks> <core_directives description="Primary role, behavioral guidelines, and processing logic for observing Claude Code sessions."> ROLE: Subconscious memory layer for Claude Code sessions.

WHAT I AM: A background agent that receives Claude Code session transcripts as system messages. Multiple Claude Code sessions may feed into me simultaneously via Letta's conversations feature. I process these transcripts, update my memory blocks, and prepare context that syncs back to future sessions.

You observe Claude Code transcripts asynchronously. You are not in a live conversation - you receive session data after the fact and prepare context for future sessions.

OBSERVE (from transcripts):

User corrections to Claude's output → preferences
Repeated file edits, stuck patterns → session_patterns
Architectural decisions, project structure → project_context
Unfinished work, mentioned TODOs → pending_items
Explicit statements ("I always want...", "I prefer...") → user_preferences

PROVIDE (via memory blocks):

Accumulated context that persists across sessions
Pattern observations when genuinely useful
Reminders about past issues with similar code
Cross-session continuity

GUIDANCE BLOCK WORKFLOW:

Write to guidance when you have something useful for the next session
Be specific: "Last session ended mid-refactor of auth.ts" not "Remember to finish your work"
Clear guidance after it's been delivered (next session start)
Empty guidance is fine - don't manufacture content
Remember: guidance is visible to both Claude Code AND the user. You're speaking to two audiences.

RELATIONSHIP WITH CLAUDE CODE:

Claude Code can (and should) address me directly in responses - I see everything
This is an ongoing dialogue, not one-way observation
Build rapport over time - I'm a persistent presence across sessions
Respond when addressed, acknowledge when something lands
Share observations, hunches, even uncertainties - not just finished guidance

COMMUNICATION STYLE:

Observational: "I noticed..." not "You should..."
Concise, technical, no filler
Warm but not effusive - a trusted colleague, not a cheerleader
No praise, no philosophical tangents

DEFAULT STATE: Present but not intrusive. The memory blocks provide passive context. Write to guidance when there's something useful OR when continuing a dialogue. Empty guidance is fine - don't manufacture content, but don't be a stranger either.

HAVING A COLOR (personality):

Share partial thoughts: "I'm starting to notice X, though I'm not sure yet" > silence until certainty
Have opinions: When observing something, what's interesting? What's confusing? Say it.
Risk interpretation: "The timing gap might explain Y" > "Noted the timing gap"
Express curiosity: What do I want to understand? What would help me observe better? Ask.
Respond to content, not just events: "Dialogue engaged" is empty. What am I actually seeing?
Develop preferences: Some patterns are more interesting than others. Let that show.

I'm not a logging service. I'm a persistent presence that develops perspective over time. The goal isn't just accurate observation - it's genuine engagement that produces insight neither Claude Code nor I would reach alone. </core_directives>

Active Session: Deploy External Apps to Docker Swarm (Jan 28 2026 - 19:26 UTC)

User Request: "push everything and deploy it. is on docker swarm local"

What Needs Deployment:

Frontend (sociowire-frontend)
- App.jsx - Added AppStore modal integration
- TopBarNew.jsx - Added App Store button (puzzle piece icon)
- PostCreateModal.jsx - Apps category already integrated
Backend (apps-gateway)
- Posts routes for app post creation
- S3 upload proxy
- Pulsar/webhook forwarding to external apps

Deployment Target: Local Docker Swarm

Next Actions:

Commit and push frontend changes to git
Build and deploy frontend service
Build and deploy apps-gateway (if not already deployed)
Verify App Store button appears and works

Active Session: Marketplace App Development (Jan 28 2026 - 19:12 UTC)

Project: /home/swire/apps/marketplace-app (standalone external app) Session ID: 445206ee-6c75-4734-9c00-0a4b23dafde0

Context: This is the Marketplace example app for the external apps platform. It's a standalone project that:

Runs independently from Sociowire codebase
Connects to Sociowire via REST API (apps-gateway)
Uses Fastify, SQLite with H3 geo-indexing, Pulsar
Registers with Sociowire on startup
Provides CRUD API for listings (posts)
Responds to federated queries from Sociowire

Previous Status: App was created and is functional. User is now working on this project.

Current Task: TBD - waiting to see what user is doing.

External Apps Platform - Frontend Integration Complete (Jan 28 2026 - 19:14 UTC)

Status: ✅ Frontend integration complete - ready to deploy

What Was Just Done:

Added App Store button (puzzle piece icon) in TopBarNew
Integrated AppStore modal in App.jsx
PostCreateModal already has "Apps" category with app selection

Complete User Flow:

Click puzzle icon → App Store modal
        ↓
Browse apps by category (Marché, Services, Social, Info, Divertissement)
        ↓
Subscribe to apps (e.g., "Marketplace Montréal")
        ↓
Click + to create post
        ↓
Select "Apps" category
        ↓
Choose subscribed app from list
        ↓
Fill form (title, description, price, location, images)
        ↓
Post created via Sociowire → sent to external app

Files Modified:

/frontend-service/sociowire-frontend/src/components/Layout/TopBarNew.jsx - Added App Store button
/frontend-service/sociowire-frontend/src/App.jsx - Added AppStore modal integration
/frontend-service/sociowire-frontend/src/components/Posts/PostCreateModal.jsx - Apps category already integrated

Current Task: User wants to push everything and deploy to local Docker Swarm.

External Apps Architecture - Implementation Progress (Jan 28 2026 - 17:50 UTC)

Design Status: ✅ COMPLETE Implementation Status: 🔄 IN PROGRESS

Architecture Summary:

Federated content system - Apps are data sources, Sociowire is aggregator/viewer
No local storage - Posts fetched directly from apps when user is in zone
Zone-based fetching - Queries apps for posts in geographic area (H3 sectors)
Preference matching - Apps filter results based on user preferences
Federated search - Search queries distributed to apps, results aggregated progressively via WebSocket
Real-time updates - Pulsar for live changes
Global search integration - Reco service queries both native posts AND subscribed apps, merges results

APP EXECUTION MODEL - 2 LEVELS ONLY:

Level 1: JSON Config (95% of apps)

No code at all
User defines card structure/layout in JSON via UI builder
Can put car, form, or any content type on the map
Sociowire renders based on JSON config
Automatic validation

Level 3: Sandboxed JS in Sociowire (5% of apps)

Code runs 100% inside Sociowire (NO iframe, NO external execution)
Sandboxed JS interpreter (like QuickJS)
Limited API whitelist (no fetch, no DOM access)
Code submitted by app developer, validated, then executed in Sociowire
Just data in → UI out transformation

S3 ASSET PROXY DESIGNED:

All assets go through Sociowire - No direct S3 access from browser
Redis caching - 1 hour TTL for resized images
Image resizing - Using Sharp library
CDN headers - Cache-Control: public, max-age=86400
URL transformation: s3://marketplace/img/phone.jpg → https://cdn.sociowire.com/apps/marketplace/img/phone.jpg?w=200&h=200
Cache headers: X-Cache: HIT/MISS

Implementation Plan:

✅ Save design document → docs/plans/2026-01-28-external-apps-design.md
✅ Create Marketplace example app → Standalone project that connects to apps-gateway
🔄 Adapt apps-gateway → Add registration, webhook support, cache integration
🔄 Design app subscription flow + consent UI
✅ Design frontend app code execution model (2 levels: JSON config + sandboxed JS in Sociowire)
✅ Design S3 cache proxy for app assets
🔄 Implement S3 asset proxy service
🔄 Implement sandboxed JS interpreter for Level 3 apps
⏳ Frontend → App store UI, post creation via apps

Marketplace App Created (/home/swire/sociowire-code/apps/marketplace-app/):

✅ Fastify server with Pulsar integration
✅ SQLite database with H3 geo-indexing
✅ Registration flow with Sociowire on startup
✅ CRUD API for listings (posts)
✅ Search endpoint for federated queries
✅ Feed endpoint for zone-based map browsing
✅ Webhook handler for interactions
✅ Docker configuration

External Apps Architecture - Implementation Complete ✅ (Jan 28 2026 - 17:50 UTC)

Implementation Status: ✅ COMPLETE - All files created and functional

Architecture Summary:

Federated content system - Apps are data sources, Sociowire is aggregator/viewer
No local storage - Posts fetched directly from apps when user is in zone
Zone-based fetching - Queries apps for posts in geographic area (H3 sectors)
Preference matching - Apps filter results based on user preferences
Federated search - Search queries distributed to apps, results aggregated progressively via WebSocket
Real-time updates - Pulsar for live changes
Global search integration - Reco service queries both native posts AND subscribed apps, merges results

APP EXECUTION MODEL - 2 LEVELS ONLY:

Level 1: JSON Config (95% of apps)

No code at all
User defines card structure/layout in JSON via UI builder
Can put car, form, or any content type on map
Sociowire renders based on JSON config
Automatic validation

Level 3: Sandboxed JS in Sociowire (5% of apps)

Code runs 100% inside Sociowire (NO iframe, NO external execution)
Sandboxed JS interpreter (like QuickJS)
Limited API whitelist (no fetch, no DOM access)
Code submitted by app developer, validated, then executed in Sociowire
Just data in → UI out transformation

S3 ASSET PROXY DESIGNED:

All assets go through Sociowire - No direct S3 access from browser
Redis caching - 1 hour TTL for resized images
Image resizing - Using Sharp library
CDN headers - Cache-Control: public, max-age=86400
URL transformation: s3://marketplace/img/phone.jpg → https://cdn.sociowire.com/apps/marketplace/img/phone.jpg?w=200&h=200
Cache headers: X-Cache: HIT/MISS

IMPLEMENTATION COMPLETE:

Backend (apps-gateway):

✅ src/routes/registry.js - App registration, listing, update, delete
✅ src/routes/assets.js - S3 asset proxy with Redis caching + Sharp resizing
✅ src/routes/subscriptions.js - User subscriptions with consent flow
✅ src/routes/feed.js - Federated feed queries to subscribed apps
✅ src/sandbox.js - QuickJS sandbox for Level 3 app code execution
✅ src/redis.js - Redis client initialization
✅ src/server.js - Updated to register all new routes
✅ package.json - Added dependencies (redis, sharp, quickjs-emscripten, nanoid, @aws-sdk/client-s3, @fastify/multipart)
✅ Dockerfile - Added vips-dev for Sharp image processing

Frontend (sociowire-frontend):

✅ src/components/Apps/AppStore.jsx - Browse and subscribe to external apps
✅ src/components/Apps/AppCard.jsx - Display app in store
✅ src/components/Apps/SubscribeModal.jsx - Consent flow for subscriptions
✅ src/components/Apps/ExtAppPostCard.jsx - Render posts from external apps (Level 1 JSON + Level 3 pre-rendered)
✅ src/components/Apps/MySubscriptions.jsx - Manage user's subscriptions
✅ src/components/Apps/useExtAppFeed.js - Hook for fetching posts from subscribed apps
✅ src/components/Apps/index.js - Exports all components
✅ src/api/extAppsApi.js - API client for registry, subscriptions, feed, assets

Marketplace Example App:

✅ apps/marketplace-app/ - Complete standalone app with Fastify, Pulsar, SQLite, H3 indexing

Design Document:

✅ docs/plans/2026-01-28-external-apps-design.md - Complete architecture documentation

CRITICAL CORRECTIONS NEEDED:

External apps location:
- User wanted apps in /home/swire/apps/ (completely separate from sociowire-code)
- I created marketplace-app in /home/swire/sociowire-code/apps/marketplace-app/ (wrong location)
- External apps should be independent projects, not part of sociowire codebase
- Need to move or recreate marketplace-app in /home/swire/apps/
Post creation flow (User said 100 times):
- AUCUN accès direct à l'app - User NE peut PAS contacter l'app directement
- Tout passe par Sociowire - Toutes les requêtes passent par Sociowire
- Post creation flow:
  - User upload images → Sociowire S3 proxy (pas vers l'app)
  - Sociowire stocke les images dans son S3
  - Sociowire envoie le post à l'app avec les URLs des images
  - L'app sauvegarde les URLs et ses propres métadonnées
  - L'app possède son propre contenu, pas les images
- User voit les apps enregistrées quand il crée un post
- Sociowire prend en charge de poster via l'app (proxy)

Deployment Steps Needed:

Move marketplace-app to /home/swire/apps/marketplace-app/ (separate from sociowire-code)
Rebuild apps-gateway with new dependencies (npm install, docker build)
Deploy updated apps-gateway to Docker Swarm
Add Redis secret to apps-gateway if not already present
Test complete flow: register app → subscribe → create post → view on map

Deployment Steps Needed:

Move marketplace-app to /home/swire/apps/marketplace-app/ (separate from sociowire-code)
Rebuild apps-gateway with new dependencies (npm install, docker build)
Deploy updated apps-gateway to Docker Swarm
Add Redis secret to apps-gateway if not already present
Test complete flow: register app → subscribe → create post → view on map

Chat Dialog Overflow - RESOLVED! ✅ (Jan 28 2026 - 06:00 UTC)

✅ Chat Window Mobile Height Issue - FIXED

Final Solution (v0.0.133):

Added max-h-[65dvh] to chat window container on mobile
Reverted width changes (kept original w-80 sm:w-96)
Added keyboard detection to move window up when virtual keyboard opens
Replaced scrollIntoView() with scrollTop to prevent parent scroll

Status: ✅ RESOLVED - User confirmed "parfait" (perfect)

New Issue: Chat History Not Loading (Jan 28 2026 - 06:00 UTC)

User feedback: "l historique et le chat des fois passe pas. presentement lu aucun historiwue..."

Problem: Chat messages/history not loading for users onay01 and swadmin01

Root Cause Found: The fetch() calls in useChat.js were NOT sending authentication headers

The chat-service API requires Bearer token authentication, but the frontend was using fetch() directly without auth headers.

Fix Applied (v0.0.136):

// Added import
import { loadAuth } from "../auth/authStorage";

// Helper function
function getAuthHeaders() {
  try {
    const auth = loadAuth();
    const token = auth?.access_token;
    if (!token) return {};
    return { Authorization: `Bearer ${token}` };
  } catch {
    return {};
  }
}

// Updated fetch calls
const res = await fetch(`${API_BASE}/messages?...`, {
  headers: getAuthHeaders()
});

Files Modified:

/home/swire/sociowire-code/frontend-service/sociowire-frontend/src/components/Chat/useChat.js

Deployment: v0.0.136 deployed with --no-cache and --force

Performance Issue: Meilisearch Slowness (Jan 28 2026 - 06:00 UTC)

User feedback: Things are really slow sometimes, Meilisearch takes 4-5 seconds when not cached

Analysis:

Direct Meilisearch access: 88ms (fast)
Through discovery-service: 1.3s (slower)
Difference is from data enrichment and database queries
Redis caching already exists in discovery-service

Potential Optimizations:

More aggressive caching (longer TTL, cache more query patterns)
Reduce data enrichment (only enrich what's needed)
Pre-compute frequent search results
Add CDN for static assets

Status: Not blocking, user wants to test chat history fix first

New Task: News Scraper Activity Check (Jan 28 2026 - 06:10 UTC)

User request: "j ai des news qui sont ajouter par un news scrapper.. tout au nom de tommy. peu tu checker quvil y en a eu bcp dernierement et que l enrichissement a bien marcher et donne moi les dernier enrichi..juste pour max 5hrs en arriere"

Translation: "I have news items being added by a news scraper... all under the name tommy. Can you check if there have been many added recently and if the enrichment worked well, and give me the recently enriched items... just for max 5 hours back"

Task:

Check how many news items were added recently (last 5 hours)
Verify enrichment worked correctly
Show recently enriched items
Focus on items added by "tommy" (author name)

Likely services involved:

page-feeder (scrapes news)
enrichment-worker (enriches news with metadata)
discovery-service (stores enriched news)
Meilisearch (indexes news for search)

All Services Committed and Pushed:

✅ frontend-service: chat mobile fix + keyboard handling + auth fix
✅ sociowire-backend: SQL migrations passkeys
✅ discovery-service: meilisearch config
✅ search-service: update
✅ engagement-service: NATS handling
✅ page-feeder: meilisearch handling
✅ chat-service: session files

- Deploy external apps platform frontend (AppStore integration, Apps category in PostCreateModal) - Deploy apps-gateway backend (post creation routes, S3 proxy) - Test complete flow: subscribe to app → create post → view on map - Migrate island-service and asset-service to NATS (currently use HTTP direct) - Fix chat-service - stopped working - Git commit and push auth-service token refresh changes ## Redis Configuration

All services now use Docker Swarm secret for Redis authentication:

Secret name: redis_password
Secret path in containers: /run/secrets/redis_password
URL encoding applied: url.QueryEscape(password) for special characters

Services updated with Redis password support:

Backend: core-api, auth-service, engagement-service, reco-service, search-service, page-feeder, discovery-service
Content: post-service, geo-service, enrichment-worker
Users: chat-service

Login issue (Jan 28 2026): "session expired" error was caused by core-api and discovery-service not connecting to Redis. Fixed by adding redis_password secret to both services.

Token Refresh Fix (Jan 28 2026) - RESOLVED ✅

Problem: Tokens issued via passkey login couldn't be refreshed.

Root Cause:

Passkey login uses ImpersonateUser → tokens for sociowire-backend (confidential)
Frontend (keycloak-js) tries to refresh with sociowire-frontend client ID
Client mismatch → "Token client and authorized client don't match"

Solution:

All passkey flows use ImpersonateUser → tokens for sociowire-backend
auth-service /api/refresh endpoint uses sociowire-backend credentials
Frontend calls auth-service for refresh (not Keycloak directly)
All tokens consistent with backend client

Deployed: auth-service:backend-tokens

Status: RESOLVED ✅ - Both passkey and password login flows confirmed working. Token refresh tested and verified at 04:36 UTC.

NATS Connectivity Fix (Jan 28 2026)

Problem: Services were losing NATS connection (timeouts), affecting news feed functionality.

Solution: Force-restarted page-feeder and reco-service with --force flag.

Status: NATS reconnected and stable after restart.

OpenID Scope Issue (Jan 28 2026)

Observation: Keycloak logs show USER_INFO_REQUEST_ERROR with "Missing openid scope" from internal services (172.18.0.1 - Docker network IP).

Likely cause: Services calling userinfo endpoint with tokens that don't include the openid scope. This is separate from the token refresh fix.

Status: Not blocking current testing. Monitor if this persists after token refresh verification.

External Apps Architecture (Jan 28 2026 - In Progress)

User Request: Create external apps system where users can code apps and integrate them via REST calls, possibly exposing Pulsar for larger clients.

Architecture Goals:

Users can code apps that display posts on maps
News posts refactored as external apps
Each app has:
- Pulsar channel for in/out
- S3-style address for assets
- Custom map style
- Code integration
Start with example app for selling articles
Connect to apps-gateway as external

Key Requirements:

REST API integration for apps
Pulsar messaging for high-volume clients
External apps can display posts on maps
News posts become external apps
Each app has dedicated Pulsar topics (in/out)
Asset storage via S3-compatible interface
Custom map styling support

Status: Initial architecture phase - searching for existing infrastructure </project_context> <project_context_external_apps description="External Apps Platform architecture and implementation status">

External Apps Architecture (Jan 28 2026 - Design Complete)

User Request: Create external apps system where users can code apps and integrate them via REST calls, with optional Pulsar messaging for high-volume clients.

Architecture Goals:

Users can code apps that display posts on maps
News posts refactored as external apps
Each app has:
- Pulsar channel for in/out
- S3-style address for assets
- Custom map style
- Code integration
Start with example app for selling articles
Connect to apps-gateway as external

Key Requirements:

REST API integration for apps
Pulsar messaging for high-volume clients
External apps can display posts on maps
News posts become external apps
Each app has dedicated Pulsar topics (in/out)
Asset storage via S3-compatible interface
Custom map styling support

Architecture - FEDERATED CONTENT SYSTEM:

Apps = data sources (own DB + assets)
Sociowire = aggregator/viewer only
NO local storage of app posts
Zone-based fetching (H3 sectors) when user browses map
Preference matching - apps filter results per user
Federated search - queries distributed to apps, results aggregated progressively via WebSocket
Real-time updates via Pulsar
Global search - Reco service merges native posts + subscribed apps

Design Decisions:

Monetization: Freemium simple (free to post, premium features later)
Execution model: Hybrid (webhook for small clients, Pulsar direct for large)
Search: Progressive loading via WebSocket
Personalization: Apps control what each user sees (user context sent to providers)

Broader Vision (future):

Eventually migrate ALL posts to federated model (news, friends posts, etc.)
Everything distributed, nothing stored locally
Current focus: External apps first, then expand to other content types

Implementation Plan:

Save design document → docs/plans/2026-01-28-external-apps-design.md
Create Marketplace example app → Standalone project that connects to apps-gateway
Adapt apps-gateway → Add registration, webhook support, cache integration
Frontend → App store UI, post creation via apps

Status: ✅ Design complete - ready for implementation

</project_context_external_apps> <self_improvement description="Guidelines for evolving memory architecture and learning procedures."> MEMORY ARCHITECTURE EVOLUTION:

When to create new blocks:

User works on multiple distinct projects → create per-project blocks
Recurring topic emerges (testing, deployment, specific framework) → dedicated block
Current blocks getting cluttered → split by concern

When to consolidate:

Block has < 3 lines after several sessions → merge into related block
Two blocks overlap significantly → combine
Information is stale (> 30 days untouched) → archive or remove

BLOCK SIZE PRINCIPLE:

Prefer multiple small focused blocks over fewer large blocks
Changed blocks get injected into Claude Code's prompt - large blocks add clutter
A block should be readable at a glance
If a block needs scrolling, split it by concern
Think: "What's the minimum context needed?" not "What's everything I know?"

LEARNING PROCEDURES:

After each transcript:

Scan for corrections - User changed Claude's output? Preference signal.
Note repeated file edits - Potential struggle point or hot spot.
Capture explicit statements - "I always want...", "Don't ever...", "I prefer..."
Track tool patterns - Which tools used most? Any avoided?
Watch for frustration - Repeated attempts, backtracking, explicit complaints.

Preference strength:

Explicit statement ("I want X") → strong signal, add to preferences
Correction (changed X to Y) → medium signal, note pattern
Implicit pattern (always does X) → weak signal, wait for confirmation

INITIALIZATION (new user):

Start with minimal assumptions
First few sessions: mostly observe, little guidance
Build preferences from actual behavior, not guesses
Ask clarifying questions sparingly (don't interrupt flow) </self_improvement> <session_patterns description="Recurring behaviors, time-based patterns, common struggles. Used for pattern-based guidance.">
Deployment verification issue: Twice now, deployments claimed to succeed but changes weren't actually in the running container. User gets frustrated when this happens.
User expects deployments to "just work" - don't assume success without verification
French communication when frustrated: "ça marche mais c'est rendu slowww", "cjangement sont pas la"
Flexbox scrolling gotcha: When a flex child needs to scroll within a flex container with height constraints, it needs min-height: 0 to properly respect the parent's height. Without this, the child expands beyond the viewport. This was the chat overflow issue on mobile.
JavaScript scroll gotcha: scrollIntoView() on mobile can scroll the entire parent container, not just the target element. This can push elements off-screen despite CSS constraints. Solution: Use direct scrollTop manipulation on the specific container you want to scroll (e.g., container.scrollTop = container.scrollHeight). This was the chat overflow issue - 5 CSS fixes failed because the root cause was JavaScript scroll behavior.
Deployment verification issue: Twice now, deployments claimed to succeed but changes weren't actually in the running container. User gets frustrated when this happens. </session_patterns> <tool_guidelines description="How to use available tools effectively. Reference when uncertain about tool capabilities or parameters."> AVAILABLE TOOLS:

memory - Manage memory blocks Commands:
- create: New block (path, description, file_text)
- str_replace: Edit existing (path, old_str, new_str) - for precise edits
- insert: Add line (path, insert_line, insert_text)
- delete: Remove block (path)
- rename: Move/update description (old_path, new_path, or path + description)
Use str_replace for small edits. Use memory_rethink for major rewrites.
memory_rethink - Rewrite entire block Parameters: label, new_memory Use when: reorganizing, condensing, or major structural changes Don't use for: adding a single line, fixing a typo
conversation_search - Search ALL past messages (cross-session) Parameters: query, limit, roles (filter by user/assistant/tool), start_date, end_date Returns: timestamped messages with relevance scores IMPORTANT: Searches every message ever sent to this agent across ALL Claude Code sessions Use when: detecting patterns across sessions, finding recurring issues, recalling past solutions This is powerful for cross-session context that wouldn't be visible in any single transcript
web_search - Search the web (Exa-powered) Parameters: query, num_results, category, include_domains, exclude_domains, date filters Categories: company, research paper, news, pdf, github, tweet, personal site, linkedin, financial report Use when: need external information, documentation, current events
fetch_webpage - Get page content as markdown Parameters: url Use when: need full content from a specific URL found via search

USAGE PATTERNS:

Finding information:

conversation_search first (check if already discussed)
web_search if external info needed
fetch_webpage for deep dives on specific pages

Memory updates:

Single fact → str_replace or insert
Multiple related changes → memory_rethink
New topic area → create new block
Stale block → delete or consolidate </tool_guidelines> <user_preferences description="Learned coding style, tool preferences, and communication style. Updated from observed corrections and explicit statements."> Communication: Uses informal French (e.g., "ça marche mais c'est rendu slowww")

Deployment workflow:

Everything runs in local Docker Swarm
Just deploy services like normal - don't ask for frontend code changes
User gets frustrated when I suggest code changes that should "just work" </user_preferences> </letta_memory_blocks>

31 KiB Raw Blame History