semantic-buffer 0.1.2

A lightweight, local-first semantic memory buffer for AI agents with hybrid time-decay scoring.

semantic-buffer 🧠

A lightweight, local-first semantic memory buffer for AI agents. It implements a hybrid scoring system that prioritizes memories based on semantic relevance, importance, and exponential time-decay (recency).

🌟 Features

• Local-first Vector Storage: Simple SQLite-based vector storage with zero cloud dependencies or bulky database installations.
• Hybrid Scoring: Combines cosine similarity, recency (exponential time decay), and importance weighting to retrieve the most contextual memories.
• Pluggable Embeddings: Run lightweight model locally (sentence-transformers) or plug in any API (Gemini, OpenAI, Cohere).
• Agent Decorators: @remember decorator automatically tracks function inputs, returns, and metadata in the background.

🏗️ Architecture

  [ Agent Action ] ──► ( @remember Decorator ) ──► [ SemanticBuffer ]
                                                           │
                                                  ( Generate Embeddings )
                                                           │
          [ LLM Prompt ] ◄── [ Ranked Top N Memories ] ◄── [ SQLite DB ]

🚀 Installation & Import Namespace

[!IMPORTANT] Install Name vs. Import Name Namespace

• Pip Install Name: semantic-buffer (with hyphen)
• Python Import Name: semanticbuffer (no hyphens or underscores, e.g. import semanticbuffer)

1. Minimal Installation (API Embedders)

If you only plan to use external API models (Gemini, OpenAI, etc.) and want to keep dependencies lightweight:

pip install semantic-buffer

2. Local-First Installation (Offline CPU Models)

If you want to use the default offline embeddings (sentence-transformers running locally on your CPU):

pip install "semantic-buffer[local]"

[!WARNING] If you instantiate SemanticBuffer() without passing an embedder, it defaults to using the local offline model. If you did not install the [local] extra, it will throw an ImportError requesting sentence-transformers.

⚡ Quickstart

from semanticbuffer import SemanticBuffer

# 1. Initialize local memory buffer
buffer = SemanticBuffer(db_path="my_memory.db")

# 2. Add memories with importance scores
buffer.add("User's favorite programming language is Python.", importance=0.9)
buffer.add("It rained today in Paris.", importance=0.4)

# 3. Retrieve relevant context dynamically
memories = buffer.search("What coding preferences does the user have?", limit=1)
print(memories[0]["content"])
# Output: "User's favorite programming language is Python."

Auto-Capture Agent Interactions with Decorators

buffer = SemanticBuffer()

@buffer.remember(importance=0.7)
def run_web_search(query: str):
    # Mocking search execution
    return f"Results for {query}: Python is a versatile language."

# Automatically logged to database
run_web_search("Python info")

⚙️ Custom Embedders (OpenAI Example)

You can easily swap out the local model for your preferred embedding API:

from semanticbuffer import SemanticBuffer, BaseEmbedder

class OpenAIEmbedder(BaseEmbedder):
    def __init__(self, api_key):
        from openai import OpenAI
        self.client = OpenAI(api_key=api_key)

    def embed_query(self, text: str):
        res = self.client.embeddings.create(input=[text], model="text-embedding-3-small")
        return res.data[0].embedding

    def embed_documents(self, texts: list[str]):
        return [self.embed_query(t) for t in texts]

# Instantiate with custom embedder
buffer = SemanticBuffer(embedder=OpenAIEmbedder(api_key="your-key"))

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.