Memory & Tools

Agentic AI Kit includes multiple memory systems for conversational context, persistent storage, shared state, and adaptive episodic memory. It also allows ordinary Python functions to be exposed as tools that agents can select and call.

Memory

Short-Term Memory

File: agentic_ai/memory/short_term.py

ShortTermMemory stores a fixed number of recent (user_input, agent_output) conversation pairs.

It is useful for maintaining local conversational context without retaining an unlimited history.

Key capabilities

Fixed-size conversation window
User and agent turn storage
Iterable memory entries
Text-formatted context
Manual memory clearing

Runnable Example

from agentic_ai.memory.short_term import ShortTermMemory

memory = ShortTermMemory(window=3)
memory.add( "What is Python?", "Python is a general-purpose programming language.",)
memory.add( "Who created it?", "Python was created by Guido van Rossum.",)
print(memory.as_text())print(list(memory))print("Stored turns:", len(memory))
memory.clear()

Long-Term Memory

File: agentic_ai/memory/long_term.py

LongTermMemory provides SQLite-backed persistent storage for agent observations, facts, decisions, and other durable entries. Unlike short-term memory, entries remain available across Python sessions.

Key capabilities

SQLite-backed persistence
Agent-specific memory entries
Recent-entry retrieval
Keyword search
Durable storage across sessions

Runnable Example

from agentic_ai.memory.long_term import LongTermMemory

memory = LongTermMemory("agent_memory.db")
entry_id = memory.log(    content="The deployment target is Python 3.12.",    agent="ReleaseManager",)
print("Stored entry:", entry_id)
memory.log(    content="The package should be published after tests pass.",    agent="ReleaseManager",)
print("\n=== RECENT ===")print(    memory.recent(        n=10,        agent="ReleaseManager",    ))
print("\n=== SEARCH ===")print(    memory.search(        "Python",        agent="ReleaseManager",    ))
memory.close()

Shared Memory

File: agentic_ai/memory/shared.py

SharedMemory is a thread-safe, in-process key-value store that can be accessed by multiple agents or workers. It is useful for shared plans, task status, intermediate results, and coordination state.

Key capabilities

Thread-safe shared state
Key-value storage
Multi-agent access
Entry deletion
Complete state clearing

Runnable Example

from agentic_ai.memory.shared import SharedMemory

shared = SharedMemory()
shared.set( "plan", "Build, test, and publish the package.",)
shared.set( "status", "in_progress",)
print(shared.get("plan"))print(shared.all())
shared.delete("status")shared.clear()

Emotion-Aware Episodic Memory

Package: agentic_ai.memory.emotion

The emotion-memory package implements deterministic, operational affective state for artificial agents. It does not claim that an agent experiences subjective human emotion. Instead, it provides inspectable computational mechanisms through which events can influence retention, identity, retrieval, and future action.

The system uses five operational labels:

Ordinary
Success
Failure
Wound
Trauma

These labels are derived from continuous appraisal values and state transitions rather than being assigned arbitrarily.

Core capabilities

Identity-conditioned appraisal and forgetting
Linked timestep memory with rooted event trees
Separate identity and action-policy ledgers
Outcome-dependent retention floors
Relevance-first retrieval
Trajectory deduplication
Relevance-gated NumPy tree attention
Correction, expiry, and deletion
Deterministic replay
Auditable memory-state reconstruction
Reinforcement-learning state encoding
Linear Q-learning with environmental reward

Outcome salience can protect the survival and fidelity of a memory, but it never bypasses the semantic relevance gate. Operational emotion labels are also not used directly as reinforcement-learning rewards.

Memory Architecture

Event → Appraisal → Operational State → Retention → Retrieval → Policy

Public Components

EmotionMemorySystem

Ingestion, correction, replay, retrieval, and audit

AppraisalEngine

Identity-sensitive appraisal and operational state

EpisodicTimeline

Linked timesteps and rooted event trees

IdentityLedger

Positive and negative contrastive self-facts

PolicyLedger

Repeat and avoidance evidence

RetentionEngine

Identity decay and outcome-dependent retention floors

RelevanceFirstRetriever

Eligibility, deduplication, and bounded ranking

TreeAttentionEngine

Attention within an eligible event tree

RLStateEncoder

Environment, identity, memory, and policy features

LinearQLearner

Deterministic Q-learning with external reward

Complete Demonstration

The full example does not require a Gemini API key.

python agentic_ai/examples/12_emotion_memory.py

The demonstration:

Ingests three recurring failures
Shows the failure → wound → trauma transition
Performs tree-attention retrieval
Constructs a reinforcement-learning state
Applies an environment-reward Q update
Deletes one event
Deterministically replays the remaining history

Architecture Documentation

The mathematical contract, assumptions, and falsification criteria are documented in:

docs/emotion_architecture.md

Frozen default parameters are stored in:

configs/emotion_architecture_v0.1.yaml
Memory Comparison

ShortTermMemory

Recent conversational turns

Current process

LongTermMemory

Durable facts and historical entries

SQLite database

SharedMemory

Coordination across agents and workers

Current process

EmotionMemorySystem

Adaptive episodic memory and policy evidence

Journal and replay architecture

Tools

ToolAgent can expose ordinary Python functions to Gemini through register_tool().

The model can then determine when a tool is required, select the appropriate function, generate its arguments, and use the returned result in its response.

Registering a Tool

from agentic_ai.agents import ToolAgent

def convert_celsius_to_fahrenheit(    celsius: float,) -> float:    """Convert a Celsius temperature to Fahrenheit."""    return celsius * 9 / 5 + 32

agent = ToolAgent(    name="Converter",    sys_prompt="Use tools for unit conversions.",)
agent.register_tool(    convert_celsius_to_fahrenheit)
response = agent.think(    "Convert 25 degrees Celsius to Fahrenheit.")
print(response)

Explicit Tool Schema

Parameter descriptions can also be supplied explicitly.

agent.register_tool( convert_celsius_to_fahrenheit, description=( "Convert a temperature from Celsius " "to Fahrenheit." ), params={ "celsius": "NUMBER", }, required=["celsius"],)

Writing Effective Tools

Functions exposed to an agent should have:

Clear and descriptive names
Type hints for every parameter
Concise docstrings
Predictable return values
Limited side effects
Explicit validation where necessary

Gemini uses the function name, parameter types, description, and docstring to decide when and how the tool should be called.

Good Tool Design

def calculate_rectangle_area(    length: float,    width: float,) -> float:    """Calculate the area of a rectangle."""    if length < 0 or width < 0:        raise ValueError(            "Length and width must be non-negative."        )
    return length * width
Avoid vague functions such as:def process(data):    ...
Prefer functions with a single clear responsibility, such as:def calculate_shipping_cost(    weight_kg: float,    distance_km: float,) -> float:    """Calculate shipping cost by weight and distance."""    ...

Memory and Tools Together

Memory allows an agent to retain relevant context and experience.

Tools allow the same agent to act on the world, perform calculations, retrieve information, or invoke external systems.

Together, they support agents that can:

Remember recent conversations
Retrieve persistent facts
Coordinate through shared state
Learn from operational experience
Select appropriate Python functions
Use tool results in subsequent reasoning
Maintain continuity across multi-step workflows

Page updated

Google Sites

Report abuse