chore: updated readme, added memory store, and added hashchaining for tamper prooof audit log in database.

Author: TobiasGleiter

README.md

@@ -1,17 +1,31 @@
-# beago: Get feedback on your code before it hits review.
+# beago: A Go framework for building LLM-powered applications.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) ![Test](https://github.com/bit8bytes/beago/actions/workflows/tests.yml/badge.svg) ![Sec Scan](https://github.com/bit8bytes/beago/actions/workflows/sec_scan.yml/badge.svg)
 
-beago uses Go's own tooling to analyze your code --- the same way Go itself sees it. The result: feedback that's actually relevant to your codebase.
+beago provides composable building blocks for LLM-powered Go applications — pipes for structured output, agents for tool-using reasoning loops, and stores for conversation history. The core library has no external dependencies.
 
-How It Works:
+## Core Concepts
 
-1. Write your code
-2. Run `beago analyze` to check it against your entire codebase
-3. Adjust before you open the PR
+- **Pipes** — simple `Input → LLM → Output` pipelines with typed, structured responses
+- **Agents** — ReAct (Reasoning + Acting) loops that interleave LLM reasoning with tool execution
+- **Stores** — tamper-evident message history with a SHA-256 hash chain, keeping LLMs stateful across turns
+- **Tools** — implement the `Tool` interface to give agents new capabilities
 
-It's that easy. Stop repeating the same review comments.
+## Quick Start
+
+```go
+// Pipe: send messages and get structured output
+pipe := pipes.New(messages, model, parser)
+result, _ := pipe.Invoke(ctx)
+
+// Agent: reason and act with tools
+agent, _ := agents.NewReAct(ctx, model, tools, storage)
+agent.Task(ctx, "Use the helloWorld tool with name Beago")
+res, _ := runner.New(agent).Run(ctx)
+```
+
+See [Examples](/docs/EXAMPLES.md) for full working examples.
 
 ## Contributions
 
-Contributions of any kind are welcome! 🙌 See [Get Involved](/docs/GET-INVOLVED.md) to get started.
+Contributions of any kind are welcome! See [Get Involved](/docs/GET-INVOLVED.md) to get started.

docs/EXAMPLES.md

@@ -3,14 +3,25 @@
 // can work with any LLM without being coupled to a specific API.
 package llms
 
-import "github.com/bit8bytes/beago/inputs/roles"
+import (
+	"time"
+
+	"github.com/bit8bytes/beago/inputs/roles"
+)
 
 // Message represents a single turn in a conversation with an LLM.
 // Role identifies who produced the content (e.g. system, user, assistant),
 // which lets the model understand conversational context and respond appropriately.
+//
+// Timestamp records when the message was added to the store.
+// Hash is a SHA-256 chain digest: SHA256(prev_hash + role + timestamp + content).
+// Each store implementation computes these in Add() so the chain is tamper-evident —
+// modifying, inserting, or deleting any message breaks every subsequent hash.
 type Message struct {
-	Role    roles.Role `json:"role"`
-	Content string     `json:"content"`
+	Role      roles.Role `json:"role"`
+	Content   string     `json:"content"`
+	Timestamp time.Time  `json:"timestamp"`
+	Hash      string     `json:"hash"`
 }
 
 // StreamHandler is a callback invoked incrementally as the model generates a response.

llms/llms.go

@@ -0,0 +1,44 @@
+package stores
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"time"
+
+	"github.com/bit8bytes/beago/llms"
+)
+
+// Stamp sets Timestamp and Hash on msg, chaining from prevHash.
+// Hash = SHA256(prevHash + role + timestamp + content).
+// Call this inside Add() before persisting, passing the hash of the last
+// stored message as prevHash (empty string for the first message).
+func Stamp(msg *llms.Message, prevHash string) {
+	msg.Timestamp = time.Now().UTC()
+
+	h := sha256.New()
+	h.Write([]byte(prevHash))
+	h.Write([]byte(msg.Role))
+	h.Write([]byte(msg.Timestamp.Format(time.RFC3339Nano)))
+	h.Write([]byte(msg.Content))
+	msg.Hash = hex.EncodeToString(h.Sum(nil))
+}
+
+// Verify replays the hash chain over msgs and returns the index of the first
+// message whose hash does not match, or -1 if the chain is intact.
+// Pass the hash that preceded the first message as prevHash
+// (empty string if msgs starts from the beginning of the store).
+func Verify(msgs []llms.Message, prevHash string) int {
+	for i, msg := range msgs {
+		h := sha256.New()
+		h.Write([]byte(prevHash))
+		h.Write([]byte(msg.Role))
+		h.Write([]byte(msg.Timestamp.Format(time.RFC3339Nano)))
+		h.Write([]byte(msg.Content))
+		want := hex.EncodeToString(h.Sum(nil))
+		if msg.Hash != want {
+			return i
+		}
+		prevHash = msg.Hash
+	}
+	return -1
+}

stores/chain.go

@@ -12,8 +12,9 @@ import (
 )
 
 type store struct {
-	mu       sync.Mutex
-	messages []llms.Message
+	mu        sync.Mutex
+	messages  []llms.Message
+	lastHash  string
 }
 
 func New() stores.Store {
@@ -24,7 +25,11 @@ func (s *store) Add(_ context.Context, msgs ...llms.Message) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
 
-	s.messages = append(s.messages, msgs...)
+	for i := range msgs {
+		stores.Stamp(&msgs[i], s.lastHash)
+		s.lastHash = msgs[i].Hash
+		s.messages = append(s.messages, msgs[i])
+	}
 	return nil
 }
 
@@ -34,6 +39,7 @@ func (s *store) Clear(_ context.Context) error {
 
 	// Retain the underlying array to avoid an allocation on the next Add.
 	s.messages = s.messages[:0]
+	s.lastHash = ""
 	return nil
 }
 

stores/memory/memory.go

@@ -20,19 +20,40 @@ import (
 
 // Store is the interface that wraps the basic message persistence methods.
 //
-// Implementations of Store must be safe for concurrent use by multiple goroutines.
+// Implementations must be safe for concurrent use by multiple goroutines.
+//
+// # Tamper-evident chain
+//
+// Every implementation must call [Stamp] on each message inside Add, passing
+// the hash of the last stored message as prevHash (empty string for the first
+// message). Stamp sets Message.Timestamp and computes Message.Hash as:
+//
+//	SHA256(prevHash + role + timestamp + content)
+//
+// This chains every message to its predecessor. Any modification, insertion,
+// or deletion of a message breaks every subsequent hash, making the history
+// tamper-evident. Callers can verify integrity by replaying the chain with
+// [Verify].
+//
+// # Minimal implementation checklist
+//
+//   - Add: call Stamp on each message before persisting; track lastHash
+//   - List: return messages in insertion order; never mutate the stored slice
+//   - Clear: reset lastHash to "" alongside clearing messages
+//   - Close: release database connections or file handles; no-op is valid
 type Store interface {
 	// Add appends one or more messages to the store. The agent calls this after
 	// every LLM turn so the full conversation history is available on the next
-	// Plan call.
+	// Plan call. Implementations must stamp each message via [Stamp] before
+	// persisting to maintain the hash chain.
 	Add(ctx context.Context, msgs ...llms.Message) error
 
 	// List returns all messages in insertion order. The agent passes the full
 	// history to the LLM on every turn so it has context from prior steps.
 	List(ctx context.Context) ([]llms.Message, error)
 
-	// Clear removes all messages, resetting the conversation. Useful when
-	// reusing a store across multiple independent agent runs.
+	// Clear removes all messages and resets the hash chain, allowing the store
+	// to be reused across independent agent runs.
 	Clear(ctx context.Context) error
 
 	// Close releases any resources held by the store (e.g. database connections).