Background Learning

This cookbook demonstrates how to use the HEBBS reflection pipeline to automatically generate insights — higher-order knowledge synthesized from raw memories. This enables your agents to learn and generalize over time.

Bulk Ingest

Start by ingesting a set of raw memories that the reflection pipeline can analyze:

import asyncio
from hebbs import HebbsClient, MemoryKind

async def ingest_sales_data(client, entity):
    interactions = [
        "Deal with Acme closed at 15% discount after 3-month negotiation",
        "Beta Corp deal lost to competitor — they wanted on-premise deployment",
        "Gamma Inc closed at full price — CTO championed the deal internally",
        "Delta Ltd requested 20% discount, settled at 10% with annual commitment",
        "Epsilon Corp deal stalled — no internal champion identified",
        "Zeta Inc closed at 5% discount — fast decision after POC",
        "Eta Corp lost — procurement process took 6 months, champion left company",
        "Theta Inc closed at full price — strong ROI case from their data team",
        "Iota Ltd deal lost — security review blocked cloud deployment",
        "Kappa Corp closed at 12% discount — multi-year deal",
        "Lambda Inc POC successful but deal stalled in legal review",
        "Mu Corp closed quickly after competitor's service outage",
    ]

    for content in interactions:
        await client.remember(
            content=content,
            entity=entity,
            kind=MemoryKind.EPISODIC,
            metadata={"source": "crm-export"},
        )

    count = await client.count(entity)
    print(f"Ingested {count} memories")

Autonomous Reflection

HEBBS runs reflection autonomously in the background. The server’s LLM integration handles clustering, insight generation, and contradiction resolution without external agent involvement. Reflection triggers automatically based on server-side configuration.

To manually trigger a reflection cycle (e.g., after a bulk ingest):

async def trigger_learning(client, entity):
    result = await client.reflect(entity_id=entity)
    print(f"Reflection complete:")
    print(f"  Memories processed: {result.memories_processed}")
    print(f"  Insights created: {result.insights_created}")
    return result

Query Insights

Retrieve the insights generated by reflection:

async def query_insights(client, entity):
    insights = await client.insights(entity, top_k=10)

    print(f"\nGenerated {len(insights)} insights:")
    for i, insight in enumerate(insights, 1):
        print(f"\n  Insight {i}: {insight.content}")
        print(f"  Confidence: {insight.metadata.get('confidence', 'N/A')}")

        # The insight's edges point back to source memories
        if insight.edges:
            print(f"  Based on {len(insight.edges)} source memories")

    return insights

Use Insights in Agent Responses

Insights appear in recall results alongside regular memories:

async def agent_with_institutional_knowledge(client, entity, question):
    results = await client.recall(
        query=question,
        entity=entity,
        strategy="similarity",
        top_k=5,
    )

    print(f"\nQuery: {question}")
    for r in results.memories:
        kind = r.memory.kind.name
        label = "INSIGHT" if kind == "INSIGHT" else "MEMORY"
        print(f"  [{label}] [{r.score:.3f}] {r.memory.content}")

Full Example

async def main():
    async with HebbsClient.connect("localhost:50051") as client:
        entity = "sales-team-knowledge"

        # Ingest raw data
        await ingest_sales_data(client, entity)

        # Trigger reflection (runs autonomously on the server)
        await trigger_learning(client, entity)

        # Query insights
        await query_insights(client, entity)

        # Use insights to answer questions
        await agent_with_institutional_knowledge(
            client, entity,
            "What patterns predict successful deal closure?",
        )
        await agent_with_institutional_knowledge(
            client, entity,
            "What are common reasons for lost deals?",
        )

asyncio.run(main())

Expected Insights

The reflection pipeline might generate insights such as:

• “Deals with an internal champion close faster and at higher prices”
• “Discount requests correlate with longer sales cycles”
• “On-premise deployment requirements and security review concerns are common blockers”
• “Quick closures often follow competitor failures or strong POC results”

These insights become part of the agent’s institutional knowledge, available via recall alongside raw memories.