### Run Bulk Permission Setup

Source: https://github.com/nobi327/amygdala/blob/main/README.md

Execute the setup script to approve all Amygdala tools for Claude Code usage.

```bash
python setup_permissions.py
```

--------------------------------

### Install Amygdala Dependencies

Source: https://github.com/nobi327/amygdala/blob/main/README.md

Clone the repository and install required Python packages including the MCP server library.

```bash
git clone https://github.com/NOBI327/amygdala.git
cd amygdala
pip install -r requirements.txt
pip install mcp  # required for MCP server
```

--------------------------------

### Example of PinMemory Usage

Source: https://github.com/nobi327/amygdala/blob/main/README.md

Shows how to use PinMemory to anchor critical information. This ensures important rules or facts are readily available to the AI.

```text
You: "Remember this: always go through staging before deploying"
   → Registered in PinMemory (max 3 slots)
```

```text
(20 turns later)
You: "Can I push to production?"
   → PinMemory auto-referenced: "You have a rule about going through staging first."
```

--------------------------------

### Register Amygdala as an MCP Server

Source: https://context7.com/nobi327/amygdala/llms.txt

Commands to install dependencies and register the Amygdala MCP server with Claude Code.

```bash
# Install dependencies
pip install -r requirements.txt
pip install mcp

# Register with Claude Code (user scope - available from any project)
claude mcp add emotion-memory \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  --scope user \
  -- python -m src.mcp_server

# Verify connection
claude
/mcp  # Should show "emotion-memory: connected"
```

--------------------------------

### Example of Emotion-Based Memory Storage

Source: https://github.com/nobi327/amygdala/blob/main/README.md

Illustrates how user input with emotional context is stored. This is useful for understanding how Amygdala captures nuanced conversational data.

```text
You: "Spent 3 weeks on that project, presented it, got no reaction..."
   → Amygdala stores: sadness 0.6 / importance 0.9 / scene: work
```

--------------------------------

### MCP Tools Usage

Source: https://github.com/nobi327/amygdala/blob/main/README.md

Examples of how to use MCP tools for storing memories, recalling memories by emotional similarity, and checking database statistics. These are typically invoked by Claude Code based on conversation context.

```shell
store_memory: "Today's code review was great. I feel the team's trust has grown."
```

```shell
recall_memories: "Good things that happened at work recently"
```

```shell
get_stats: {}
```

--------------------------------

### Example of Emotion-Based Memory Retrieval

Source: https://github.com/nobi327/amygdala/blob/main/README.md

Demonstrates how past emotionally significant experiences are recalled in future conversations. This enables contextually relevant AI responses.

```text
You: "How should I prepare for the next presentation?"
   → Previous presentation experience recalled via emotional similarity
   → AI generates advice informed by that past experience
```

--------------------------------

### RelationalGraphEngine Node and Edge Creation

Source: https://context7.com/nobi327/amygdala/llms.txt

Demonstrates creating nodes (people, topics) and edges with emotion tags and relationships using RelationalGraphEngine. Requires Config and DatabaseManager.

```python
from src.relational_graph import RelationalGraphEngine
from src.config import Config
from src.db import DatabaseManager

config = Config()
db = DatabaseManager(":memory:")
db.init()
graph = RelationalGraphEngine(config, db)

# Create nodes
alice = graph.upsert_node(
    label="Alice",
    type="person",
    emotion_vec={"trust": 0.9, "joy": 0.7},
    aliases=["Alice-san", "A-chan"]
)
print(f"Created node: {alice['label']} (id={alice['id']})")

project = graph.upsert_node(
    label="Backend Refactoring",
    type="topic",
    emotion_vec={"anticipation": 0.8, "importance": 0.9}
)
```

```python
# Create edge with relationship tags
edge = graph.upsert_edge(
    source_label="Alice",
    target_label="Backend Refactoring",
    emotion_vec={"trust": 0.8, "anticipation": 0.7},
    tag_labels=["lead", "architect", "owner"]
)
print(f"Edge created with {len(edge['tags'])} tags")
```

--------------------------------

### Run All Tests with Coverage

Source: https://github.com/nobi327/amygdala/blob/main/README.md

Execute all tests in the 'tests/' directory and generate a coverage report including missing lines. This command is useful for a comprehensive check of the codebase.

```bash
python -m pytest tests/ -v --cov=src --cov-report=term-missing
```

--------------------------------

### Register MCP Server in Configuration Files

Source: https://github.com/nobi327/amygdala/blob/main/README.md

Manually add the MCP server configuration to Claude Code or Claude Desktop settings files.

```json
{
  "mcpServers": {
    "emotion-memory": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "/path/to/amygdala"
    }
  }
}
```

--------------------------------

### Configure Amygdala Memory System

Source: https://context7.com/nobi327/amygdala/llms.txt

Initialize the memory system with custom parameters for database paths, memory retention, emotion weights, and graph limits.

```python
config = Config(
    DB_PATH="memory.db",
    WORKING_MEMORY_TURNS=10,      # Last N turns in working memory
    PIN_MEMORY_SLOTS=3,           # Max pinned items
    PIN_TTL_TURNS=10,             # Turns before pin expiry check

    # Emotion search weights
    EMOTION_WEIGHT=0.4,
    SCENE_WEIGHT=0.35,
    META_WEIGHT=0.25,

    # Time decay (half-life in days)
    HALF_LIFE_NORMAL=30,
    HALF_LIFE_PINNED=60,
    HALF_LIFE_FREQUENT=45,        # For recall_count > 5

    # Graph limits
    GRAPH_MAX_ACTIVE_NODES=100,
    GRAPH_MAX_EDGES_PER_NODE=20,
    GRAPH_MAX_TAGS_PER_EDGE=10,
    TAG_CANDIDATE_THRESHOLD=3,     # Activations needed for tag promotion
)
```

--------------------------------

### Run Core Layer Tests with Coverage Threshold

Source: https://github.com/nobi327/amygdala/blob/main/README.md

Execute tests and check coverage for the core layers of the 'src/' directory. The test run will fail if the coverage is below 80%, ensuring a minimum quality standard.

```bash
python -m pytest tests/ --cov=src --cov-fail-under=80
```

--------------------------------

### Initialize MemorySystem Python API

Source: https://context7.com/nobi327/amygdala/llms.txt

Direct programmatic access to the MemorySystem class using dependency injection.

```python
from src.config import Config
from src.db import DatabaseManager
from src.memory_system import MemorySystem
from src.llm_adapter import AnthropicAdapter

# Initialize with dependency injection
config = Config.from_env()
db = DatabaseManager(config.DB_PATH)
db.init()

llm_client = AnthropicAdapter(default_model=config.BACKMAN_MODEL)
memory_system = MemorySystem(llm_client, db, config)

# Process a conversation turn (full pipeline)
response = memory_system.process_turn("I'm worried about the deadline")
```

--------------------------------

### Configure Amygdala via Environment Variables

Source: https://context7.com/nobi327/amygdala/llms.txt

Sets Amygdala configuration parameters using environment variables. These settings are then loaded by the Config class.

```python
import os

# Environment variable configuration
os.environ["EMS_DB_PATH"] = "/data/amygdala.db"
os.environ["EMS_BACKMAN_MODEL"] = "claude-haiku-4-5-20251001"
os.environ["EMS_VERBOSE"] = "false"  # Hide emotion details in responses
os.environ["EMS_DAEMON_POLL_INTERVAL"] = "5.0"  # Seconds
os.environ["EMS_DAEMON_RECALL_TOP_K"] = "3"

config = Config.from_env()
```

--------------------------------

### Verify MCP Connection

Source: https://github.com/nobi327/amygdala/blob/main/README.md

Launch Claude Code and check the status of the MCP connection.

```bash
claude          # Launch Claude Code
/mcp            # Check MCP connection status
```

--------------------------------

### Register MCP Server via CLI

Source: https://github.com/nobi327/amygdala/blob/main/README.md

Register the Amygdala MCP server with Claude Code using the command line interface.

```bash
claude mcp add emotion-memory \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  --scope user \
  -- python -m src.mcp_server
```

--------------------------------

### Run Standalone Frontman

Source: https://github.com/nobi327/amygdala/blob/main/README.md

Commands to run the Amygdala system in standalone mode using the front man script or a demo script. Ensure you are in the correct directory.

```bash
python -m src.frontman
```

```bash
python scripts/demo.py
```

--------------------------------

### Configure API Key

Source: https://github.com/nobi327/amygdala/blob/main/README.md

Set the ANTHROPIC_API_KEY environment variable to enable API mode for automatic emotion tagging.

```bash
# Add to your shell config (.bashrc / .zshrc / etc.)
export ANTHROPIC_API_KEY="sk-ant-..."
```

--------------------------------

### Retrieve Memory System Statistics

Source: https://context7.com/nobi327/amygdala/llms.txt

Fetches high-level metrics including total memory count, emotion distribution, and diversity indices.

```python
get_stats()
```

--------------------------------

### Recall Memories by Emotional Similarity

Source: https://context7.com/nobi327/amygdala/llms.txt

Usage of the recall_memories tool to retrieve relevant information based on queries and emotional context.

```python
# MCP Tool: recall_memories
# Parameters:
#   query (str): Search query describing what to recall
#   top_n (int, optional): Max results, default 5
#   emotions (dict, optional): Emotion vector for similarity search

# Example 1: Recall by query with emotion context
recall_memories(
    query="Previous presentation experiences",
    emotions={"sadness": 0.5, "importance": 0.8},
    top_n=3
)
# Returns:
# [
#   {"id": 42, "content": "The 3-week project presentation got no reaction...",
#    "emotion": "sadness", "score": 0.87},
#   {"id": 35, "content": "First demo went well, team was engaged...",
#    "emotion": "joy", "score": 0.62},
#   {"id": 28, "content": "Quarterly review presentation prep...",
#    "emotion": "anticipation", "score": 0.58}
# ]

# Example 2: Simple text-based recall (emotions inferred from query)
recall_memories(query="What did we decide about the deployment strategy?")
# Returns memories matching the emotional context of the query
```

--------------------------------

### SearchEngine Time Decay and Full Search

Source: https://context7.com/nobi327/amygdala/llms.txt

Computes time decay based on days, pin status, and recall count, and performs a full memory search with emotion and scene filtering. Requires initialized SearchEngine.

```python
# Time decay calculation
decay = engine.compute_time_decay(
    days_ago=15.0,
    pinned_flag=False,
    recall_count=3
)
print(f"Time decay (15 days): {decay:.3f}")  # ~0.71
```

```python
# Full search with scoring
results = engine.search_memories(
    emotion_vec={"importance": 0.9, "trust": 0.7},
    scenes=["work"],
    top_k=10
)
for r in results:
    print(f"[{r['id']}] {r['content'][:50]}... (score: {r['score']:.3f})")
```

--------------------------------

### Store Memories with Emotion Tags

Source: https://context7.com/nobi327/amygdala/llms.txt

Usage of the store_memory tool to save content with emotional vectors, scene labels, and entity relationships.

```python
# MCP Tool: store_memory
# Parameters:
#   text (str): Content to store
#   context (str, optional): Additional context
#   emotions (dict, optional): 10-axis emotion vector (0.0-1.0)
#   scenes (list, optional): Scene tags (max 3)
#   entities (list, optional): Entity data for graph building

# Example 1: Store with explicit emotion scores
store_memory(
    text="The 3-week project presentation got no reaction from anyone",
    emotions={
        "joy": 0.0, "sadness": 0.6, "anger": 0.2, "fear": 0.1,
        "surprise": 0.3, "disgust": 0.1, "trust": 0.1, "anticipation": 0.0,
        "importance": 0.9, "urgency": 0.2
    },
    scenes=["work"]
)
# Returns: {"memory_id": 42, "emotion": "sadness", "score": 0.6}

# Example 2: Store with entity extraction for graph building
store_memory(
    text="Working on FastAPI migration with Tanaka-san, need to finish by Friday",
    emotions={"anticipation": 0.7, "importance": 0.8, "urgency": 0.6},
    scenes=["work"],
    entities=[
        {
            "label": "Tanaka",
            "type": "person",
            "aliases": ["Tanaka-san"],
            "relations": [{"target": "FastAPI migration", "tags": ["collaborator"]}]
        },
        {"label": "FastAPI migration", "type": "topic"}
    ]
)
# Returns: {"memory_id": 43, "emotion": "importance", "score": 0.8}
```

--------------------------------

### RelationalGraphEngine Context and Decay

Source: https://context7.com/nobi327/amygdala/llms.txt

Retrieves entity context from the graph, applies decay to tags, and cleans up stale connections. Assumes graph is initialized.

```python
# Search by emotion similarity
similar_nodes = graph.search_by_emotion(
    emotion_vec={"trust": 0.8, "joy": 0.5},
    top_k=5
)
```

```python
# Get entity context for conversation
context = graph.get_entity_context("Alice", hops=2)
print(f"Entity: {context['entity']}")
print(f"Primary emotions: {context['primary_emotion']}")
print(f"Related: {context['related_entities']}")
print(f"Tags: {context['active_tags']}")
```

```python
# Apply decay to all tags and clean up stale connections
decay_result = graph.apply_decay()
print(f"Decayed: {decay_result['decayed_tags']} tags")
print(f"Removed: {decay_result['removed_tags']} weak tags")
print(f"Archived: {decay_result['archived_edges']} tagless edges")
```

--------------------------------

### SearchEngine Emotion and Scene Similarity

Source: https://context7.com/nobi327/amygdala/llms.txt

Calculates cosine similarity between emotion vectors and Jaccard coefficient for scene matching. Requires SearchEngine, Config, and DatabaseManager.

```python
from src.search_engine import SearchEngine
from src.config import Config
from src.db import DatabaseManager

config = Config()
db = DatabaseManager(":memory:")
db.init()
engine = SearchEngine(config, db)

# Cosine similarity between emotion vectors
query_emotion = {"joy": 0.8, "trust": 0.6, "anticipation": 0.4}
memory_emotion = {"joy": 0.7, "trust": 0.5, "surprise": 0.3}

similarity = engine.cosine_similarity(
    query_emotion, memory_emotion,
    axes=config.EMOTION_AXES  # 8 basic emotions
)
print(f"Emotion similarity: {similarity:.3f}")  # ~0.92
```

```python
# Scene similarity (Jaccard coefficient)
scene_sim = engine.scene_similarity(
    memory_scenes=["work", "learning"],
    current_scenes=["work", "daily"]
)
print(f"Scene similarity: {scene_sim:.3f}")  # 0.33
```

--------------------------------

### Access Metadata Axes and Tags

Source: https://context7.com/nobi327/amygdala/llms.txt

Retrieve the available emotion axes, meta axes, and scene tags defined in the current configuration.

```python
print(f"Emotion axes: {config.EMOTION_AXES}")
# ('joy', 'sadness', 'anger', 'fear', 'surprise', 'disgust', 'trust', 'anticipation')

print(f"Meta axes: {config.META_AXES}")
# ('importance', 'urgency')

print(f"Scene tags: {config.SCENE_TAGS}")
# ('work', 'relationship', 'hobby', 'health', 'learning', 'daily', 'philosophy', 'meta')
```

--------------------------------

### Create Graph Nodes Table

Source: https://github.com/nobi327/amygdala/blob/main/docs/relational-graph-design.md

Defines the schema for the 'graph_nodes' table, storing entities with their labels, types, aliases, mention counts, and base emotion vectors. Includes a unique index on the label for efficient lookups.

```sql
CREATE TABLE IF NOT EXISTS graph_nodes (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    label TEXT NOT NULL,
    type TEXT NOT NULL CHECK(type IN ('person','topic','item','place','event')),
    aliases TEXT DEFAULT '[]',
    first_seen DATETIME DEFAULT CURRENT_TIMESTAMP,
    last_seen DATETIME DEFAULT CURRENT_TIMESTAMP,
    mention_count INTEGER DEFAULT 1,
    joy REAL DEFAULT 0, sadness REAL DEFAULT 0,
    anger REAL DEFAULT 0, fear REAL DEFAULT 0,
    surprise REAL DEFAULT 0, disgust REAL DEFAULT 0,
    trust REAL DEFAULT 0, anticipation REAL DEFAULT 0,
    importance REAL DEFAULT 0, urgency REAL DEFAULT 0,
    archived BOOLEAN DEFAULT FALSE
);
CREATE UNIQUE INDEX IF NOT EXISTS idx_node_label ON graph_nodes(label);
```

--------------------------------

### Retrieve Active Context

Source: https://context7.com/nobi327/amygdala/llms.txt

Fetches auto-recalled memories from the background daemon for proactive injection.

```python
get_active_context()
```

--------------------------------

### get_stats

Source: https://context7.com/nobi327/amygdala/llms.txt

Retrieve statistics about the memory system, including total memories, emotion distribution, and diversity metrics.

```APIDOC
## get_stats

### Description
Retrieve memory system statistics including total memories, emotion distribution, and diversity metrics.

### Method
`get_stats`

### Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **total_memories** (integer) - The total number of memories stored.
- **emotion_distribution** (object) - A map of emotions to their distribution counts.
  - **joy** (integer)
  - **sadness** (integer)
  - **anger** (integer)
  - **fear** (integer)
  - **surprise** (integer)
  - **disgust** (integer)
  - **trust** (integer)
  - **anticipation** (integer)
- **diversity_index** (float) - A metric representing the diversity of memories.
- **pinned_count** (integer) - The number of currently pinned memories.
- **auto_tagging** (boolean) - Indicates if auto-tagging is enabled.

#### Response Example
```json
{
  "total_memories": 247,
  "emotion_distribution": {
    "joy": 45, "sadness": 32, "anger": 12, "fear": 8,
    "surprise": 28, "disgust": 5, "trust": 67, "anticipation": 50
  },
  "diversity_index": 0.78,
  "pinned_count": 2,
  "auto_tagging": true
}
```
```

--------------------------------

### Python TypedDict for EntityContext

Source: https://github.com/nobi327/amygdala/blob/main/docs/relational-graph-design.md

Defines the type hint for EntityContext using TypedDict, intended for use with the Frontman system. It summarizes an entity, including its primary emotion, active tags, related entities, and confidence score. This is used to pass context to the Frontman.

```python
class EntityContext(TypedDict):
    """Frontmanに渡すサマリー形式"""
    entity: str
    primary_emotion: dict
    active_tags: List[str]
    related_entities: List[str]
    confidence: float
```

--------------------------------

### List and Manage Graph Entities

Source: https://context7.com/nobi327/amygdala/llms.txt

Lists active entities with optional filtering and archives entities from the graph.

```python
list_graph_entities(top_n=5)
```

```python
list_graph_entities(type_filter="person", top_n=10)
```

```python
forget_entity(entity="Old project")
```

--------------------------------

### Pin Memories to Working Memory

Source: https://context7.com/nobi327/amygdala/llms.txt

Usage of the pin_memory tool to keep important information accessible in working memory.

```python
# MCP Tool: pin_memory
# Parameters:
#   content (str): Information to pin
#   label (str, optional): Short label for the pin
```

--------------------------------

### Frontmanへの情報伝達フォーマット

Source: https://github.com/nobi327/amygdala/blob/main/docs/amygdala-relational-graph-proposal.md

BackmanからFrontmanへ渡されるサマリー情報の構造。

```json
{
  entity: "上司",
  primary_emotion: {frustration: 0.7, trust: 0.3},
  active_tags: ["ストレス源", "1on1関連"],
  related_entities: ["Notionテンプレート", "部署異動"],
  confidence: 0.8
}
```

--------------------------------

### MCP Tool: recall_memories

Source: https://context7.com/nobi327/amygdala/llms.txt

Searches and retrieves relevant memories based on emotional similarity and query content.

```APIDOC
## recall_memories

### Description
Search and retrieve relevant memories by emotional similarity. Scans for patterns suggesting past memories would be relevant.

### Parameters
- **query** (str) - Required - Search query describing what to recall
- **top_n** (int) - Optional - Max results, default 5
- **emotions** (dict) - Optional - Emotion vector for similarity search

### Request Example
{
  "query": "Previous presentation experiences",
  "emotions": {"sadness": 0.5, "importance": 0.8},
  "top_n": 3
}

### Response
#### Success Response (200)
- **results** (list) - List of memory objects containing id, content, emotion, and score
```

--------------------------------

### Manage Pinned Memories

Source: https://context7.com/nobi327/amygdala/llms.txt

Functions to pin, list, and release critical memories within the system.

```python
pin_memory(
    content="Always deploy to staging before production",
    label="deployment-rule"
)
```

```python
pin_memory(
    content="Budget limit is $50k, deadline is March 15",
    label="project-constraints"
)
```

```python
list_pinned_memories()
```

```python
unpin_memory(pin_id=1)
```

--------------------------------

### get_active_context

Source: https://context7.com/nobi327/amygdala/llms.txt

Retrieve auto-recalled memories from the background daemon, useful for proactive memory injection.

```APIDOC
## get_active_context

### Description
Retrieve auto-recalled memories from the background daemon. Call every turn for proactive memory injection.

### Method
`get_active_context`

### Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **recalled_memories** (array) - A list of memories that were auto-recalled.
  - **id** (integer) - The ID of the recalled memory.
  - **content** (string) - The content of the recalled memory.
  - **score** (float) - The relevance score of the recalled memory.
- **updated_at** (string) - The timestamp when the context was last updated.
- **trigger_emotion** (object) - The dominant emotion detected that triggered the recall.
  - **sadness** (float)
  - **importance** (float)
- **trigger_scenes** (array of strings) - Scenes or contexts associated with the trigger.
- **source_memory_id** (integer) - The ID of the memory that triggered this context recall.

#### Response Example (Context Available)
```json
{
  "recalled_memories": [
    {"id": 42, "content": "The 3-week project presentation...", "score": 0.82},
    {"id": 38, "content": "Discussed presentation tips with mentor...", "score": 0.71}
  ],
  "updated_at": "2024-01-15T10:30:00Z",
  "trigger_emotion": {"sadness": 0.5, "importance": 0.8},
  "trigger_scenes": ["work"],
  "source_memory_id": 43
}
```

#### Response Example (No Context Available)
```json
{
  "recalled_memories": [],
  "status": "no_context_available"
}
```
```

--------------------------------

### Access Amygdala Memory Components

Source: https://context7.com/nobi327/amygdala/llms.txt

Demonstrates direct access to Amygdala's memory sub-components for adding turns, managing pins, and performing searches.

```python
memory_system.working_memory.add_turn("Hello", "Hi there!")
turns = memory_system.working_memory.get_turns()
print(f"Working memory has {memory_system.working_memory.count()} turns")
```

```python
memory_system.pin_memory.add_pin("Important rule here", label="rule-1")
pins = memory_system.pin_memory.get_active_pins()
expired = memory_system.pin_memory.decrement_ttl()
```

```python
emotion_vec = {"joy": 0.2, "trust": 0.8, "importance": 0.7}
results = memory_system.search_engine.search_memories(
    emotion_vec, scenes=["work"], top_k=5
)
```

```python
memory_system.graph_engine.upsert_node(
    label="Alice", type="person",
    emotion_vec={"trust": 0.9, "joy": 0.6},
    aliases=["Alice-san"]
)
context = memory_system.graph_engine.get_entity_context("Alice", hops=2)
```

```python
memory_system.close()
```

--------------------------------

### RelationalGraphEngine Turn Processing

Source: https://context7.com/nobi327/amygdala/llms.txt

Processes a turn of conversation, updating the graph with extracted entities, emotions, and relationships, then applying decay and limits. Requires initialized RelationalGraphEngine.

```python
# Full turn processing (extraction → update → decay → limits)
result = graph.process_turn(
    text="Met with Alice about the backend refactoring progress",
    emotion_vec={"trust": 0.7, "anticipation": 0.6}
)
print(f"Updated {result['nodes_affected']} nodes, {result['edges_affected']} edges")
```

--------------------------------

### MemorySystem Python API

Source: https://context7.com/nobi327/amygdala/llms.txt

Programmatic access to the MemorySystem class for use outside the MCP environment.

```APIDOC
## MemorySystem Python API

### Description
Use the MemorySystem class directly for programmatic access outside MCP.

### Initialization
```python
from src.config import Config
from src.db import DatabaseManager
from src.memory_system import MemorySystem
from src.llm_adapter import AnthropicAdapter

# Initialize with dependency injection
config = Config.from_env()
db = DatabaseManager(config.DB_PATH)
db.init()

llm_client = AnthropicAdapter(default_model=config.BACKMAN_MODEL)
memory_system = MemorySystem(llm_client, db, config)
```

### Process Turn

#### Description
Processes a single conversational turn through the full memory pipeline.

#### Method
`memory_system.process_turn(user_input: str)`

#### Parameters
- **user_input** (string) - Required - The input from the user for the current turn.

#### Request Example
```python
response = memory_system.process_turn("I'm worried about the deadline")
```

#### Response
- The structure of the `response` object depends on the pipeline's output, typically containing processed memory information and potential actions.
```

--------------------------------

### Create Graph Tags Table

Source: https://github.com/nobi327/amygdala/blob/main/docs/relational-graph-design.md

Defines the schema for the 'graph_tags' table, which stores labels and associated metadata for edges. It includes fields for the edge ID, tag label, strength, activation count, decay rate, and a confirmation flag. This table allows for detailed tagging of relationships.

```sql
CREATE TABLE IF NOT EXISTS graph_tags (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    edge_id INTEGER NOT NULL REFERENCES graph_edges(id),
    label TEXT NOT NULL,
    strength REAL DEFAULT 0.5,
    activation_count INTEGER DEFAULT 1,
    decay_rate REAL DEFAULT 0.05,
    confirmed BOOLEAN DEFAULT FALSE,
    created DATETIME DEFAULT CURRENT_TIMESTAMP,
    last_activated DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(edge_id, label)
);
```

--------------------------------

### MCP Tool: store_memory

Source: https://context7.com/nobi327/amygdala/llms.txt

Stores text with associated emotion tags and scene labels into long-term memory.

```APIDOC
## store_memory

### Description
Stores text with emotion tags and scene labels into long-term memory. The system auto-detects significant patterns to determine storage priority.

### Parameters
- **text** (str) - Required - Content to store
- **context** (str) - Optional - Additional context
- **emotions** (dict) - Optional - 10-axis emotion vector (0.0-1.0)
- **scenes** (list) - Optional - Scene tags (max 3)
- **entities** (list) - Optional - Entity data for graph building

### Request Example
{
  "text": "The 3-week project presentation got no reaction from anyone",
  "emotions": {"sadness": 0.6, "importance": 0.9},
  "scenes": ["work"]
}

### Response
#### Success Response (200)
- **memory_id** (int) - Unique identifier for the stored memory
- **emotion** (str) - Primary emotion detected
- **score** (float) - Emotional intensity score
```

--------------------------------

### Memory Management API

Source: https://context7.com/nobi327/amygdala/llms.txt

Functions for pinning, listing, and unpinning memories within the Amygdala system.

```APIDOC
## Pin a critical rule

### Description
Pins a critical rule to memory with a specified content and label.

### Method
`pin_memory`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **content** (string) - Required - The content of the rule to be pinned.
- **label** (string) - Required - A label for the pinned rule.

### Request Example
```json
{
  "content": "Always deploy to staging before production",
  "label": "deployment-rule"
}
```

### Response
#### Success Response (200)
- **pin_id** (integer) - The ID of the pinned memory.
- **content** (string) - The content of the pinned memory.
- **label** (string) - The label of the pinned memory.
- **slots_used** (integer) - The number of memory slots used.
- **max_slots** (integer) - The maximum number of memory slots available.

#### Response Example
```json
{
  "pin_id": 1,
  "content": "Always deploy to staging...",
  "label": "deployment-rule",
  "slots_used": 1,
  "max_slots": 3
}
```

## Pin a project constraint

### Description
Pins a project constraint to memory with specified content and label.

### Method
`pin_memory`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **content** (string) - Required - The content of the project constraint.
- **label** (string) - Required - A label for the pinned constraint.

### Request Example
```json
{
  "content": "Budget limit is $50k, deadline is March 15",
  "label": "project-constraints"
}
```

### Response
#### Success Response (200)
- **pin_id** (integer) - The ID of the pinned memory.
- **slots_used** (integer) - The number of memory slots used.
- **max_slots** (integer) - The maximum number of memory slots available.

#### Response Example
```json
{
  "pin_id": 2,
  "slots_used": 2,
  "max_slots": 3
}
```

## List all active pins

### Description
Retrieves a list of all currently active pinned memories.

### Method
`list_pinned_memories`

### Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **Array of pinned memory objects**
  - **pin_id** (integer) - The ID of the pinned memory.
  - **content** (string) - The content of the pinned memory.
  - **label** (string) - The label of the pinned memory.
  - **ttl_remaining** (integer) - The time-to-live remaining for the pin.

#### Response Example
```json
[
  {
    "pin_id": 1,
    "content": "Always deploy to staging...",
    "label": "deployment-rule",
    "ttl_remaining": 8
  },
  {
    "pin_id": 2,
    "content": "Budget limit is $50k...",
    "label": "project-constraints",
    "ttl_remaining": 10
  }
]
```

## Release a pin

### Description
Releases a pinned memory, migrating it to long-term storage with high priority.

### Method
`unpin_memory`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **pin_id** (integer) - Required - The ID of the pin to release.

### Request Example
```json
{
  "pin_id": 1
}
```

### Response
#### Success Response (200)
- **released_pin_id** (integer) - The ID of the memory that was released.
- **migrated_to_memory_id** (integer) - The ID of the memory after migration to long-term storage.

#### Response Example
```json
{
  "released_pin_id": 1,
  "migrated_to_memory_id": 156
}
```
```

--------------------------------

### Create Graph Edges Table

Source: https://github.com/nobi327/amygdala/blob/main/docs/relational-graph-design.md

Defines the schema for the 'graph_edges' table, storing relationships between nodes. It includes fields for source and target node IDs, strength, confidence, activation counts, and emotion vectors. A unique constraint prevents duplicate edges between the same pair of nodes.

```sql
CREATE TABLE IF NOT EXISTS graph_edges (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    source_id INTEGER NOT NULL REFERENCES graph_nodes(id),
    target_id INTEGER NOT NULL REFERENCES graph_nodes(id),
    strength REAL DEFAULT 1.0,
    confidence REAL DEFAULT 0.5,
    last_activated DATETIME DEFAULT CURRENT_TIMESTAMP,
    activation_count INTEGER DEFAULT 1,
    joy REAL DEFAULT 0, sadness REAL DEFAULT 0,
    anger REAL DEFAULT 0, fear REAL DEFAULT 0,
    surprise REAL DEFAULT 0, disgust REAL DEFAULT 0,
    trust REAL DEFAULT 0, anticipation REAL DEFAULT 0,
    importance REAL DEFAULT 0, urgency REAL DEFAULT 0,
    archived BOOLEAN DEFAULT FALSE,
    UNIQUE(source_id, target_id)
);
```

--------------------------------

### Backmanの責務拡張

Source: https://github.com/nobi327/amygdala/blob/main/docs/amygdala-relational-graph-proposal.md

Backmanエージェントにおける関係性グラフ管理の統合構造。

```text
Backman（追加）
  └── 関係性グラフ管理
       ├── ノード/エッジの生成・更新
       ├── タグの生成・昇格・減衰処理
       └── グラフベースの関連メモリ検索
```

--------------------------------

### Query Relational Entity Graph

Source: https://context7.com/nobi327/amygdala/llms.txt

Searches for entities and their connections within the graph, supporting depth-based expansion.

```python
query_entity_graph(entity="Tanaka")
```

```python
query_entity_graph(entity="FastAPI", hops=2)
```

--------------------------------

### タグの減衰計算式

Source: https://github.com/nobi327/amygdala/blob/main/docs/amygdala-relational-graph-proposal.md

最終活性化日時からの経過時間に基づいた強度減衰の計算式。

```text
current_strength = initial_strength × e^(-decay_rate × days_since_last_activation)
```

--------------------------------

### MCP Tool: pin_memory

Source: https://context7.com/nobi327/amygdala/llms.txt

Pins important information to working memory for constant reference.

```APIDOC
## pin_memory

### Description
Pin important information to working memory (max 3 slots) for constant reference. Pinned items have extended half-life.

### Parameters
- **content** (str) - Required - Information to pin
- **label** (str) - Optional - Short label for the pin
```

--------------------------------

### Python TypedDict for GraphNode

Source: https://github.com/nobi327/amygdala/blob/main/docs/relational-graph-design.md

Defines the type hint for a graph node using TypedDict, specifying fields like id, label, type, aliases, mention count, and base emotion vector. This aids in static analysis and code clarity within the Python codebase.

```python
from typing import TypedDict, List, Optional

class GraphNode(TypedDict):
    id: int
    label: str
    type: str
    aliases: List[str]
    mention_count: int
    base_emotion: dict
```

--------------------------------

### list_graph_entities

Source: https://context7.com/nobi327/amygdala/llms.txt

List all active entities in the relational graph, sorted by importance and mention frequency.

```APIDOC
## list_graph_entities

### Description
List all active entities in the relational graph, sorted by importance and mention frequency.

### Method
`list_graph_entities`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **type_filter** (string) - Optional - Filters the results to a specific entity type (e.g., 'person', 'topic', 'item', 'place', 'event').
- **top_n** (integer) - Optional - Limits the number of results returned. Defaults to 20.

### Request Example
```json
{
  "top_n": 5
}
```

```json
{
  "type_filter": "person",
  "top_n": 10
}
```

### Response
#### Success Response (200)
- **Array of entity objects**
  - **id** (integer) - The unique identifier for the entity.
  - **label** (string) - The name or label of the entity.
  - **type** (string) - The type of the entity (e.g., 'person', 'topic').
  - **aliases** (array of strings) - Alternative names or aliases for the entity.
  - **mention_count** (integer) - The number of times the entity has been mentioned.

#### Response Example
```json
[
  {"id": 1, "label": "Tanaka", "type": "person", "aliases": ["Tanaka-san"], "mention_count": 23},
  {"id": 5, "label": "FastAPI migration", "type": "topic", "aliases": [], "mention_count": 18},
  {"id": 3, "label": "Production server", "type": "item", "aliases": ["prod"], "mention_count": 15}
]
```
```

--------------------------------

### グラフ構造のノード定義

Source: https://github.com/nobi327/amygdala/blob/main/docs/amygdala-relational-graph-proposal.md

会話に登場するエンティティを保持するノードのデータ構造。

```text
Node {
  id: string                    # 一意識別子
  type: enum                    # person | topic | item | place | event
  label: string                 # 表示名（例："上司", "Amygdalaプロジェクト"）
  first_seen: datetime          # 初出日時
  last_seen: datetime           # 最終言及日時
  mention_count: int            # 累計言及回数
  base_emotion: EmotionVector   # このエンティティに対する基底感情
}
```

--------------------------------

### 関係性タグの定義

Source: https://github.com/nobi327/amygdala/blob/main/docs/amygdala-relational-graph-proposal.md

エッジに付与される関係性の性質ラベル。

```text
Tag {
  label: string                 # タグ名（例："ストレス源", "協力者", "学習対象"）
  created: datetime             # 生成日時
  strength: float (0.0-1.0)    # タグ強度（減衰対象）
  activation_count: int         # このタグが活性化された回数
  decay_rate: float             # タグ固有の減衰率
}
```

--------------------------------

### query_entity_graph

Source: https://context7.com/nobi327/amygdala/llms.txt

Search the relational graph for a specific entity and its connections, returning related entities, emotion vectors, and relationship tags.

```APIDOC
## query_entity_graph

### Description
Search the relational graph for a specific entity and its connections. Returns related entities, emotion vectors, and relationship tags.

### Method
`query_entity_graph`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **entity** (string) - Required - The name of the entity to search for (partial matches are supported).
- **hops** (integer) - Optional - The search depth, either 1 or 2. Defaults to 1.

### Request Example
```json
{
  "entity": "Tanaka"
}
```

```json
{
  "entity": "FastAPI",
  "hops": 2
}
```

### Response
#### Success Response (200)
- **entity** (string) - The primary entity queried.
- **primary_emotion** (object) - The dominant emotion associated with the entity.
  - **trust** (float)
  - **joy** (float)
  - **anticipation** (float)
- **active_tags** (array of strings) - Tags associated with the entity.
- **related_entities** (array of strings) - Entities directly or indirectly connected to the queried entity.
- **confidence** (float) - The confidence score of the relationship.

#### Response Example
```json
{
  "entity": "Tanaka",
  "primary_emotion": {"trust": 0.7, "joy": 0.5, "anticipation": 0.4},
  "active_tags": ["collaborator", "mentor", "python-expert"],
  "related_entities": ["FastAPI migration", "Backend team", "Code reviews"],
  "confidence": 0.85
}
```

#### Response Example (2-hop)
```json
{
  "entity": "FastAPI migration",
  "related_entities": ["Tanaka", "Backend team", "Python", "SQLAlchemy", "Docker"],
  "confidence": 0.85
}
```
```

--------------------------------

### Python TypedDict for GraphTag

Source: https://github.com/nobi327/amygdala/blob/main/docs/relational-graph-design.md

Defines the type hint for a graph tag using TypedDict. It specifies fields such as id, label, strength, activation count, confirmation status, and decay rate. This structure is used to represent relationship labels within the graph.

```python
class GraphTag(TypedDict):
    id: int
    label: str
    strength: float
    activation_count: int
    confirmed: bool
    decay_rate: float
```

--------------------------------

### グラフ構造のエッジ定義

Source: https://github.com/nobi327/amygdala/blob/main/docs/amygdala-relational-graph-proposal.md

ノード間の関係性を表すエッジのデータ構造。

```text
Edge {
  source: NodeID
  target: NodeID
  tags: List[Tag]               # 関係性の性質を表すタグ群
  emotion_vector: EmotionVector # Plutchik 8軸 + importance + urgency
  strength: float (0.0-1.0)    # 接続強度（減衰対象）
  confidence: float (0.0-1.0)  # 推論信頼度（サンプル数ベース）
  last_activated: datetime      # 最終活性化日時
  activation_count: int         # 累計活性化回数
}
```

--------------------------------

### Python TypedDict for GraphEdge

Source: https://github.com/nobi327/amygdala/blob/main/docs/relational-graph-design.md

Defines the type hint for a graph edge using TypedDict. It includes fields for edge ID, source and target node IDs, associated tags, emotion vector, strength, confidence, and activation count. This structure is used within the relational_graph.py module.

```python
class GraphEdge(TypedDict):
    id: int
    source_id: int
    target_id: int
    tags: List["GraphTag"]
    emotion_vector: dict
    strength: float
    confidence: float
    activation_count: int
```

--------------------------------

### forget_entity

Source: https://context7.com/nobi327/amygdala/llms.txt

Archives an entity and all its associated edges from the relational graph using a soft delete mechanism.

```APIDOC
## forget_entity

### Description
Archive an entity and all its edges from the relational graph (soft delete).

### Method
`forget_entity`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **entity** (string) - Required - The name of the entity to archive.

### Request Example
```json
{
  "entity": "Old project"
}
```

### Response
#### Success Response (200)
- **forgotten_entity** (string) - The name of the entity that was archived.
- **archived_edges** (integer) - The number of edges associated with the entity that were archived.

#### Response Example
```json
{
  "forgotten_entity": "Old project",
  "archived_edges": 7
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.