AttentionDB Developer Guide

Table of Contents

Overview

AttentionDB is a salience-first, LLM-native memory and query engine that unifies vector recall, relational logic, and deterministic scripts. It enables intelligent agents to recall, explain, and act on the right data at the right time.

Key Features

  • Salience-based memory recall
  • Deterministic script execution
  • Cluster-gated recall optimization
  • Graph-based attention scoring
  • Shortcut compilation for frequent queries

Getting Started

Prerequisites

  • PostgreSQL database
  • Qdrant vector database
  • Python 3.8+

Installation

pip install attentiondb

Basic Setup

  1. Initialize the databases:
from attentiondb import AttentionDB

db = AttentionDB(
    postgres_url="postgresql://user:pass@localhost/attentiondb",
    qdrant_url="http://localhost:6333"
)
  1. Configure your first parser:
# parser_config.yaml
parser:
  type: "support_ticket"
  extract_fields: ["user_id", "issue", "created_at"]
  enrich: ["sentiment", "product_category"]
  1. Start ingesting data:
db.ingest_entities(
    data_source="tickets.json",
    parser_config="parser_config.yaml"
)

Core Concepts

Entities

The fundamental unit of memory in AttentionDB. Each entity contains:

  • Embedding vector
  • Metadata
  • Call graph/relationship edges
  • Cluster assignment

Attention Mechanism

Entities are scored using a multi-factor attention formula:

attention_score = sim(query, entity) * (
    1 + λ1*recency
      + λ2*ownership
      + λ3*call_graph
      + λ4*cluster_boost
      + λ5*fan_in
      + λ6*contextual_match
)

Salience Profiles

Pre-configured weighting schemes for different use cases:

# Example: support-default.yaml
weights:
  recency: 0.9
  ownership: 0.6
  cluster_boost: 1.2
  call_graph: 0.3
  fan_in: 0.1
  contextual_match: 0.8

API Reference

Query API

Basic Query

results = db.query(
    query="Why did this user request a refund?",
    salience_profile="support-default"
)

Shortcut Execution

result = db.execute_shortcut(
    shortcut_id="sales_by_store_and_date",
    params={"store_id": 124, "date": "2024-02-05"}
)

Memory Injection

context = db.inject(
    query="debug checkout flow",
    token_budget=1000
)

REST API Endpoints

GET /query
POST /shortcut/:id
GET /inject
GET /explain/:entity_id

Integration Guide

LangChain Integration

from attend import inject_context
from langchain import Agent

context = inject_context("debug checkout flow")
agent.memory.load_documents(context)

AutoGen Integration

import attend
from autogen import Agent

top_mem = attend.query(
    "show ticket history",
    profile="support-fast"
)
agent.state.memory = top_mem

CLI Usage

# Query memory
attend query "help debug checkout flow"

# Test parser
attend parse --test data.json

# Inject context
attend inject "help me debug checkout"

Advanced Topics

Custom Parser Development

  1. Define schema:
parser:
  name: "custom_parser"
  version: "1.0"
  fields:
    - name: "id"
      type: "string"
      required: true
    - name: "content"
      type: "text"
      enrichments: ["sentiment", "category"]
  1. Implement parser:
from attentiondb import BaseParser

class CustomParser(BaseParser):
    def parse(self, data):
        # Implementation
        pass

    def enrich(self, entity):
        # Enrichment logic
        pass

Salience Profile Tuning

# Override weights per query
db.query(
    "debug checkout flow",
    lambda_overrides={
        "recency": 0.8,
        "call_graph": 1.5
    }
)

Performance Guidelines

Capacity Limits (v1.x)

  • Up to 1M entities per node
  • 100-300ms query latency
  • 2-3GB RAM per 100K entities
  • Max 2 hops, 200 edges per graph walk

Optimization Tips

  1. Use cluster-gated recall:
db.query(
    query="...",
    use_cluster_gate=True,
    max_clusters=3
)
  1. Implement shortcuts for frequent queries:
db.register_shortcut(
    id="frequent_query",
    params=["user_id"],
    script="...",
    clusters=["relevant_cluster"]
)
  1. Configure caching:
db.configure_cache(
    max_size=1000,
    ttl_seconds=3600
)

Security Considerations

Script Execution

  • Scripts run in isolated Python sandbox
  • No I/O or external imports allowed
  • Memory and runtime limits enforced

Multi-tenant Usage

# Scope queries to namespace
db.query(
    query="...",
    namespace="team_123",
    scope_id="user_456"
)

Audit Logging

# Enable detailed audit logs
db.configure_audit(
    log_level="detailed",
    retention_days=30
)

Troubleshooting

Common Issues

  1. High Latency
  • Check cluster configuration
  • Verify index optimization
  • Review graph walk depth
  1. Poor Recall Quality
  • Validate parser output
  • Check embedding quality
  • Review salience profile

Debugging Tools

# Explain entity recall
attend explain --entity-id xyz

# Profile query performance
attend profile "query text"

# Validate parser
attend parse --test --verbose data.json

Contributing

  1. Fork the repository
  2. Create feature branch
  3. Submit pull request

See CONTRIBUTING.md for detailed guidelines.

License

AttentionDB is licensed under the MIT License. See LICENSE for details.