flock-core 0.2.18__tar.gz → 0.3.2__tar.gz

{flock_core-0.2.18 → flock_core-0.3.2}/.github/workflows/deploy-documentation.yml

@@ -3,6 +3,7 @@ on:
   push:
     branches:
       - master  # or master
+      - docs/*  # or docs/*
 
 jobs:
   deploy:

{flock_core-0.2.18 → flock_core-0.3.2}/.github/workflows/deploy-whiteduck-pypi.yml

@@ -6,6 +6,8 @@ on:
   push:
     branches:
       - master # Replace with your default branch
+    paths:
+      - 'pyproject.toml'  # Only trigger on changes to pyproject.toml (version number)
 
 jobs:
   build-and-publish:

{flock_core-0.2.18 → flock_core-0.3.2}/.gitignore

@@ -26,6 +26,7 @@ share/python-wheels/
 *.egg
 MANIFEST
 logs/
+metrics/
 
 
 # PyInstaller

{flock_core-0.2.18 → flock_core-0.3.2}/.vscode/settings.json

@@ -13,8 +13,22 @@
         "source.organizeImports.ruff": "always",
         "source.fixAll.ruff": "always"
     },
-    // we try to make semantic highlighting look good
+    "editor.fontFamily": "'Jetbrains Mono', 'FiraCode Nerd Font', 'Hack Nerd Font', 'monospace'",
+    "editor.smoothScrolling": true,
+    "terminal.integrated.fontFamily": "'Jetbrains Mono', 'FiraCode Nerd Font', 'Hack Nerd Font', 'monospace'",
+    "editor.renderIndentGuides": false,
+    "editor.renderWhitespace": "none",
+    //"terminal.integrated.lineHeight": 1.5,
+    "editor.fontSize": 15.5,
+    "editor.fontLigatures": true,
+    //"editor.lineHeight": 1.5,
+    "editor.minimap.enabled": false,
+    "editor.tabSize": 2,
+    "editor.semanticTokenColorCustomizations": {
+        "enabled": true
+    },
     "editor.semanticHighlighting.enabled": true,
+    // we try to make semantic highlighting look good
     // prevent VSCode from modifying the terminal colors
     "terminal.integrated.minimumContrastRatio": 0,
     "cSpell.words": [

{flock_core-0.2.18 → flock_core-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flock-core
-Version: 0.2.18
+Version: 0.3.2
 Summary: Declarative LLM Orchestration at Scale
 Author-email: Andre Ratzenberger <andre.ratzenberger@whiteduck.de>
 License-File: LICENSE
@@ -14,6 +14,7 @@ Requires-Dist: dspy==2.5.42
 Requires-Dist: duckduckgo-search>=7.3.2
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: loguru>=0.7.3
+Requires-Dist: matplotlib>=3.10.0
 Requires-Dist: msgpack>=1.1.0
 Requires-Dist: opentelemetry-api>=1.30.0
 Requires-Dist: opentelemetry-exporter-jaeger-proto-grpc>=1.21.0
@@ -21,13 +22,19 @@ Requires-Dist: opentelemetry-exporter-jaeger>=1.21.0
 Requires-Dist: opentelemetry-exporter-otlp>=1.30.0
 Requires-Dist: opentelemetry-instrumentation-logging>=0.51b0
 Requires-Dist: opentelemetry-sdk>=1.30.0
+Requires-Dist: pillow>=10.4.0
+Requires-Dist: prometheus-client>=0.21.1
 Requires-Dist: pydantic>=2.10.5
 Requires-Dist: python-box>=7.3.2
 Requires-Dist: python-decouple>=3.8
 Requires-Dist: questionary>=2.1.0
 Requires-Dist: rich>=13.9.4
+Requires-Dist: sentence-transformers>=3.4.1
 Requires-Dist: temporalio>=1.9.0
+Requires-Dist: tiktoken>=0.8.0
 Requires-Dist: toml>=0.10.2
+Requires-Dist: tqdm>=4.67.1
+Requires-Dist: zep-python>=2.0.2
 Provides-Extra: all-tools
 Requires-Dist: docling>=2.18.0; extra == 'all-tools'
 Requires-Dist: markdownify>=0.14.1; extra == 'all-tools'
@@ -350,9 +357,49 @@ Super simple rules to remember:
 1. Point the first agent to the next one using `hand_off`
 2. Make sure their inputs and outputs match up
 
+### Tools of the trade
+
+Of couse no agent framework is complete without using tools.
+Flock enables agents to use any python function you pass as tool or to use one of the plenty default tools
+
+```python
+bloggy = FlockAgent(
+    name="bloggy",
+    input="blog_idea: str|The topic to blog about",
+    output=(
+        "funny_blog_title: str|A catchy title for the blog, "
+        "blog_headers: list[str]|List of section headers for the blog"
+        "analysis_results: dict[str,Any] | Result of calculated analysis if necessary"
+    )
+    tools=[basic_tools.web_search_duckduckgo, basic_tools.code_eval],
+)
+
+result = flock.run(
+    input={"blog_idea": "A blog about cats, with an analysis how old the oldest cat became in days"},
+    start_agent=bloggy
+)
+```
+
+These tools are available out of the box (needs `flock-core[tools]`):
+
+- web_search_tavily
+- web_search_duckduckgo
+- get_web_content_as_markdown
+- get_anything_as_markdown (uses docling and needs `flock-core[all-tools]`)
+- evaluate_math
+- code_eval
+- get_current_time
+- count_words
+- extract_urls
+- extract_numbers
+- json_parse_safe
+- save_to_file
+- read_from_file
+
+
 That's all there is to it! `bloggy` comes up with amazing headers, and `content_writer` turns them into full blog sections. No more writer's block! 🎉
 
-And this is just the beginning - you can chain as many agents as you want. Maybe add a proofreader? Or an SEO optimizer? But let's not get ahead of ourselves! 😉
+And this is just the beginning - you can chain as many agents as you want. Maybe add a proofreader? Or add memory? Or an SEO optimizer? But let's not get ahead of ourselves! 😉
 
 So far we've barely scratched the surface of what flock has to offer, and we're currently hard at work building up the documentation for all the other super cool features Flock has up its sleeve! Stay tuned! 🚀
 

{flock_core-0.2.18 → flock_core-0.3.2}/README.md

@@ -311,9 +311,49 @@ Super simple rules to remember:
 1. Point the first agent to the next one using `hand_off`
 2. Make sure their inputs and outputs match up
 
+### Tools of the trade
+
+Of couse no agent framework is complete without using tools.
+Flock enables agents to use any python function you pass as tool or to use one of the plenty default tools
+
+```python
+bloggy = FlockAgent(
+    name="bloggy",
+    input="blog_idea: str|The topic to blog about",
+    output=(
+        "funny_blog_title: str|A catchy title for the blog, "
+        "blog_headers: list[str]|List of section headers for the blog"
+        "analysis_results: dict[str,Any] | Result of calculated analysis if necessary"
+    )
+    tools=[basic_tools.web_search_duckduckgo, basic_tools.code_eval],
+)
+
+result = flock.run(
+    input={"blog_idea": "A blog about cats, with an analysis how old the oldest cat became in days"},
+    start_agent=bloggy
+)
+```
+
+These tools are available out of the box (needs `flock-core[tools]`):
+
+- web_search_tavily
+- web_search_duckduckgo
+- get_web_content_as_markdown
+- get_anything_as_markdown (uses docling and needs `flock-core[all-tools]`)
+- evaluate_math
+- code_eval
+- get_current_time
+- count_words
+- extract_urls
+- extract_numbers
+- json_parse_safe
+- save_to_file
+- read_from_file
+
+
 That's all there is to it! `bloggy` comes up with amazing headers, and `content_writer` turns them into full blog sections. No more writer's block! 🎉
 
-And this is just the beginning - you can chain as many agents as you want. Maybe add a proofreader? Or an SEO optimizer? But let's not get ahead of ourselves! 😉
+And this is just the beginning - you can chain as many agents as you want. Maybe add a proofreader? Or add memory? Or an SEO optimizer? But let's not get ahead of ourselves! 😉
 
 So far we've barely scratched the surface of what flock has to offer, and we're currently hard at work building up the documentation for all the other super cool features Flock has up its sleeve! Stay tuned! 🚀
 

flock_core-0.3.2/docs/assets/drawio/architecture.drawio

@@ -0,0 +1,44 @@
+<mxfile host="65bd71144e">
+    <diagram id="iQ7YuHOuaVDECIdskFDT" name="Page-1">
+        <mxGraphModel dx="88" dy="620" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" background="light-dark(#FFFFFF, #d8cfb1)" math="0" shadow="1">
+            <root>
+                <mxCell id="0"/>
+                <mxCell id="1" parent="0"/>
+                <mxCell id="2" value="sequenceDiagram&#xa;    participant Client&#xa;    participant Flock&#xa;    participant FlockAgent&#xa;    participant Registry&#xa;    participant Context&#xa;    participant LLM&#xa;    &#xa;    Client-&gt;&gt;Flock: run_async(agent, input)&#xa;    Flock-&gt;&gt;Registry: get_agent(name)&#xa;    Registry--&gt;&gt;Flock: agent instance&#xa;    &#xa;    Flock-&gt;&gt;Context: initialize_context(agent, input)&#xa;    &#xa;    Flock-&gt;&gt;FlockAgent: run(inputs)&#xa;    activate FlockAgent&#xa;    &#xa;    FlockAgent-&gt;&gt;FlockAgent: initialize(inputs)&#xa;    FlockAgent-&gt;&gt;FlockAgent: _evaluate(inputs)&#xa;    &#xa;    FlockAgent-&gt;&gt;LLM: process with tools/prompts&#xa;    LLM--&gt;&gt;FlockAgent: response&#xa;    &#xa;    FlockAgent-&gt;&gt;FlockAgent: terminate(inputs, result)&#xa;    FlockAgent--&gt;&gt;Flock: result&#xa;    deactivate FlockAgent&#xa;    &#xa;    Flock--&gt;&gt;Client: final result" style="shadow=0;dashed=0;align=left;strokeWidth=1;shape=mxgraph.mermaid.abstract.mermaid;labelBackgroundColor=#ffffff;noLabel=1;theme=default;" parent="1" vertex="1">
+                    <mxGeometry x="271" y="360" width="300" height="300" as="geometry"/>
+                </mxCell>
+            </root>
+        </mxGraphModel>
+    </diagram>
+    <diagram id="mQwFuZfSuTjpqv4SXbYC" name="Page-2">
+        <mxGraphModel dx="354" dy="259" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" background="light-dark(#FFFFFF, #ffffde)" math="0" shadow="1">
+            <root>
+                <mxCell id="0"/>
+                <mxCell id="1" parent="0"/>
+                <mxCell id="gh-ZxXSGDDD0mwRwWCxR-1" value="graph TD&#xa;    subgraph Client Application&#xa;        client[Client Code]&#xa;    end&#xa;&#xa;    subgraph Flock Framework&#xa;        orchestrator[Flock Orchestrator]&#xa;        registry[Agent Registry]&#xa;        context[Context Manager]&#xa;        &#xa;        subgraph Agents&#xa;            base[FlockAgent Base]&#xa;&#xa;        end&#xa;        &#xa;        subgraph Execution&#xa;            local[Local Executor]&#xa;            temporal[Temporal Executor]&#xa;        end&#xa;        &#xa;        subgraph Core Services&#xa;            logging[Logging System]&#xa;            tools[Tool Registry]&#xa;            formatter[Output Formatters]&#xa;        end&#xa;    end&#xa;&#xa;    subgraph External Services&#xa;        llm[Language Models]&#xa;        temporal_server[Temporal Server]&#xa;    end&#xa;&#xa;    %% Client interactions&#xa;    client --&gt; orchestrator&#xa;    &#xa;    %% Orchestrator relations&#xa;    orchestrator --&gt; registry&#xa;    orchestrator --&gt; context&#xa;    orchestrator --&gt; local&#xa;    orchestrator --&gt; temporal&#xa;    &#xa;    %% Agent relations&#xa;    base --&gt; tools&#xa;    base --&gt; logging&#xa;    base --&gt; formatter&#xa;&#xa;    &#xa;    %% Execution relations&#xa;    local --&gt; llm&#xa;    temporal --&gt; temporal_server&#xa;    temporal_server --&gt; llm&#xa;    &#xa;    %% Registry relations&#xa;    registry --&gt; base&#xa;    registry --&gt; tools&#xa;&#xa;    %% Style&#xa;    classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px;&#xa;    classDef external fill:#e1f5fe,stroke:#0288d1,stroke-width:2px;&#xa;    classDef core fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px;&#xa;    &#xa;    class llm,temporal_server external;&#xa;    class orchestrator,registry,context,base,local,temporal core;" style="shadow=0;dashed=0;align=left;strokeWidth=1;shape=mxgraph.mermaid.abstract.mermaid;labelBackgroundColor=#ffffff;noLabel=1;theme=default;" vertex="1" parent="1">
+                    <mxGeometry x="274" y="325" width="300" height="300" as="geometry"/>
+                </mxCell>
+            </root>
+        </mxGraphModel>
+    </diagram>
+    <diagram id="sh9ImpPZNdK_Mo0HMCRx" name="Page-3">
+        <mxGraphModel dx="1237" dy="800" grid="0" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="0" pageScale="1" pageWidth="850" pageHeight="1100" background="light-dark(#FFFFFF,#E8E8E8)" math="0" shadow="0">
+            <root>
+                <mxCell id="0"/>
+                <mxCell id="1" parent="0"/>
+                <mxCell id="84CqISvRR4rrSDVKXhkM-1" value="graph TD&#xa;    subgraph Memory Storage&#xa;        A[New Input/Output] --&gt; B[Create Embedding]&#xa;        B --&gt; C[Extract Concepts]&#xa;        C --&gt; D[Create Memory Entry]&#xa;        D --&gt; E{Store Memory}&#xa;        E --&gt;|Recent| F[Short Term Memory]&#xa;        E --&gt;|Frequent Use| G[Long Term Memory]&#xa;        D --&gt; H[Update Concept Graph]&#xa;    end&#xa;&#xa;classDef process fill:#73B7E7,stroke:#333,stroke-width:2px;&#xa;classDef storage fill:#90EE90,stroke:#333,stroke-width:2px;&#xa;class A,B,C,D process;&#xa;class F,G,H storage;" style="shadow=0;dashed=0;align=left;strokeWidth=1;shape=mxgraph.mermaid.abstract.mermaid;labelBackgroundColor=#ffffff;noLabel=1;theme=default;" parent="1" vertex="1">
+                    <mxGeometry x="-20" y="10" width="300" height="300" as="geometry"/>
+                </mxCell>
+                <mxCell id="84CqISvRR4rrSDVKXhkM-2" value="graph TD&#xa;    subgraph Memory Retrieval&#xa;        A1[Query] --&gt; B1[Create Query Embedding]&#xa;        A1 --&gt; C1[Extract Query Concepts]&#xa;        B1 --&gt; D1{Similarity Search}&#xa;        C1 --&gt; E1{Concept Spreading}&#xa;        D1 --&gt; F1[Find Similar Memories]&#xa;        E1 --&gt; G1[Find Related Concepts]&#xa;        F1 --&gt; H1[Score &amp; Rank Results]&#xa;        G1 --&gt; H1&#xa;        H1 --&gt; I1[Return Best Matches]&#xa;    end&#xa;&#xa;classDef query fill:#FFB6C1,stroke:#333,stroke-width:2px;&#xa;classDef process fill:#73B7E7,stroke:#333,stroke-width:2px;&#xa;classDef result fill:#90EE90,stroke:#333,stroke-width:2px;&#xa;class A1,B1,C1 query;&#xa;class D1,E1,F1,G1 process;&#xa;class H1,I1 result;&#xa;" style="shadow=0;dashed=0;align=left;strokeWidth=1;shape=mxgraph.mermaid.abstract.mermaid;labelBackgroundColor=#ffffff;noLabel=1;theme=default;" parent="1" vertex="1">
+                    <mxGeometry x="240" y="10" width="300" height="300" as="geometry"/>
+                </mxCell>
+                <mxCell id="84CqISvRR4rrSDVKXhkM-3" value="graph LR&#xa;    subgraph Concept Graph&#xa;        A2[Space] --&gt; B2[Rockets]&#xa;        B2 --&gt; C2[Physics]&#xa;        C2 --&gt; D2[Energy]&#xa;        B2 --&gt; E2[Engineering]&#xa;        A2 --&gt; F2[Astronomy]&#xa;        F2 --&gt; G2[Planets]&#xa;    end&#xa;&#xa;classDef concept fill:#FFE4B5,stroke:#333,stroke-width:2px;&#xa;class A2,B2,C2,D2,E2,F2,G2 concept;" style="shadow=0;dashed=0;align=left;strokeWidth=1;shape=mxgraph.mermaid.abstract.mermaid;labelBackgroundColor=#ffffff;noLabel=1;theme=default;" parent="1" vertex="1">
+                    <mxGeometry x="520" y="-60" width="300" height="300" as="geometry"/>
+                </mxCell>
+                <mxCell id="84CqISvRR4rrSDVKXhkM-4" value="sequenceDiagram&#xa;    participant Q as Query&#xa;    participant M as Memory System&#xa;    participant ST as Short Term&#xa;    participant LT as Long Term&#xa;    participant CG as Concept Graph&#xa;&#xa;    Q-&gt;&gt;M: Search Request&#xa;    activate M&#xa;    M-&gt;&gt;ST: Check Recent Memories&#xa;    M-&gt;&gt;LT: Check Important Memories&#xa;    M-&gt;&gt;CG: Spread Activation&#xa;    CG--&gt;&gt;M: Related Concepts&#xa;    ST--&gt;&gt;M: Similar Recent Memories&#xa;    LT--&gt;&gt;M: Similar Important Memories&#xa;    M-&gt;&gt;M: Score &amp; Rank Results&#xa;    M--&gt;&gt;Q: Return Best Matches&#xa;    deactivate M" style="shadow=0;dashed=0;align=left;strokeWidth=1;shape=mxgraph.mermaid.abstract.mermaid;labelBackgroundColor=#ffffff;noLabel=1;theme=default;" parent="1" vertex="1">
+                    <mxGeometry y="290" width="820" height="650" as="geometry"/>
+                </mxCell>
+            </root>
+        </mxGraphModel>
+    </diagram>
+</mxfile>

flock_core-0.3.2/docs/core-concepts/memory.md

@@ -0,0 +1,355 @@
+# Flock Memory System: How It Works
+
+Ever wondered how AI can remember and learn from past interactions? Flock's memory system works a lot like human memory, but with some cool technical tricks! Let's break it down.
+
+## 🧠 The Big Picture
+
+Imagine you're organizing a huge library of experiences. This library has:
+
+- Recent memories (short-term)
+- Important, well-used memories (long-term)
+- Connections between related topics
+- A smart way to find relevant information
+
+That's basically what Flock's memory system does!
+
+
+
+## 💭 How Memories Are Stored
+
+### 1. Memory Entries
+
+Each memory is stored with:
+
+- What went in (inputs)
+- What came out (outputs)
+- When it happened (timestamp)
+- How often it's used (access count)
+- Special "embedding" (think of it as the memory's fingerprint)
+- Related concepts (like tags or keywords)
+
+```python
+memory = {
+    "inputs": {"question": "How do rockets work?"},
+    "outputs": {"answer": "Rockets work by..."},
+    "timestamp": "2025-02-20",
+    "access_count": 3,
+    "concepts": ["rockets", "space", "physics"]
+}
+```
+
+### 2. Smart Fingerprinting (Embeddings)
+
+- Every memory gets a special "fingerprint" (a list of numbers)
+- Similar memories have similar fingerprints
+- This helps find related memories quickly
+- Uses a smart AI model (Sentence Transformers) to create these fingerprints
+
+![Concept Graph](../assets/images/memory_flow.png){ width="600" }
+
+### 3. Concept Graph
+
+- Maintains a network of connected concepts
+- Like how your brain connects "rocket" with "space" and "physics"
+- The more often concepts appear together, the stronger their connection
+- Helps find related memories even if they use different words
+
+
+![Concept Graph](../assets/images/memory_concepts.png){ width="600" }
+
+## 🔍 How Memories Are Retrieved
+
+![Concept Graph](../assets/images/memory_flow_chart.png){ width="600" }
+
+### 1. Similarity Search
+
+When looking for memories, the system:
+
+1. Creates a fingerprint of your query
+2. Compares it with stored memory fingerprints
+3. Finds the closest matches
+
+Like finding books in a library by topic, not just exact title matches!
+
+### 2. Memory Scoring
+
+Each memory gets a score based on:
+
+```
+Final Score = Similarity × Decay × Reinforcement × Decay Factor
+
+Where:
+
+- Similarity: How well it matches your query (0-1)
+- Decay: Newer memories score higher
+- Reinforcement: Frequently used memories score higher
+- Decay Factor: Adjusts based on usefulness
+```
+
+### 3. Memory Evolution
+
+Memories change over time:
+
+- Frequently used memories get stronger (higher decay factor)
+- Unused memories fade (lower decay factor)
+- Very frequently used memories move to long-term storage
+- Just like how human memories work!
+
+## 🎯 Memory Operations
+
+You can interact with memory in different ways:
+
+### 1. Semantic Search
+
+```python
+"topic -> memory.semantic(threshold=0.8)"
+# Finds memories that are conceptually similar
+```
+
+### 2. Exact Match
+
+```python
+"topic -> memory.exact"
+# Finds memories that match precisely
+```
+
+### 3. Combined Search
+
+```python
+"topic -> memory.semantic | memory.exact | memory.combine"
+# Uses both similarity and exact matching
+```
+
+## 🌟 Cool Features
+
+### 1. Clustering
+
+- Similar memories are grouped together
+- Makes retrieval faster
+- Helps identify patterns in the knowledge
+
+### 2. Spreading Activation
+
+- When finding related concepts, activation "spreads" through the concept network
+- Like how thinking about "rockets" might lead to "space travel" then "astronauts"
+- Helps discover relevant but not obvious connections
+
+### 3. Automatic Promotion
+
+- Frequently used memories automatically move to long-term storage
+- Like how you remember important things better than one-off events
+- Helps maintain a balance between fresh and important memories
+
+## 📈 Memory Over Time
+
+As the system is used:
+
+1. Short-term memory collects recent interactions
+2. Important memories move to long-term storage
+3. The concept graph grows and strengthens connections
+4. Clustering helps organize growing knowledge
+5. Search becomes smarter with more context
+
+## 🔧 Under The Hood Example
+
+Let's say you ask about rockets:
+
+1. **Storage**
+   ```python
+   Entry(
+       id="mem_123",
+       inputs={"query": "How do rockets work?"},
+       embedding=[0.1, 0.2, ...],  # Fingerprint
+       concepts={"rockets", "physics", "space"}
+   )
+   ```
+
+2. **Retrieval**
+   ```python
+   # When you ask about "space travel":
+   query_embedding = compute_embedding("space travel")
+   similar_memories = find_similar(query_embedding)
+   concept_memories = spread_activation({"space", "travel"})
+   results = combine_and_rank(similar_memories, concept_memories)
+   ```
+
+3. **Learning**
+   ```python
+   # After using a memory:
+   memory.access_count += 1
+   memory.decay_factor *= 1.1  # Gets stronger
+   if memory.access_count > 10:
+       promote_to_long_term(memory)
+   ```
+
+## 🎓 Why This Matters
+
+This system gives Flock:
+
+1. Better context awareness
+2. More consistent responses
+3. Learning from interactions
+4. Efficient knowledge retrieval
+5. Natural knowledge evolution
+
+Just like a human assistant would remember past conversations and learn from experience!
+
+
+
+In addition to the memory there is a declarative memory mapping system in which you define what memory you want to extract. Let's look at it!
+
+
+## 🗺️ Memory Mapping System
+
+## 🔗 Basic Syntax
+
+Memory mappings use this pattern:
+```python
+"input -> operation1 | operation2 | operation3 -> output"
+```
+Where:
+- `->` points to where data should flow
+- `|` chains operations together (like pipes in Unix)
+- Operations can have parameters in parentheses
+
+## 🧪 Available Operations
+
+### 1. Semantic Search
+```python
+"query -> memory.semantic(threshold=0.8)"
+```
+Parameters:
+- `threshold`: Similarity cutoff (0-1)
+- `max_results`: Maximum number of results
+- `scope`: 'local', 'global', or 'both'
+
+### 2. Exact Match
+```python
+"topic -> memory.exact"
+```
+Looks for exact matches in memory entries. Good for when you need precise matching.
+
+### 3. Filter
+```python
+"memory.filter(recency='7d', relevance=0.5)"
+```
+Parameters:
+- `recency`: Time window ('24h', '7d', etc.)
+- `relevance`: Minimum relevance score
+- `metadata`: Custom metadata filters
+
+### 4. Sort
+```python
+"memory.sort(by='relevance', ascending=False)"
+```
+Parameters:
+- `by`: 'relevance', 'recency', or 'access_count'
+- `ascending`: Sort direction
+
+### 5. Combine
+```python
+"memory.combine(weights={'semantic': 0.7, 'exact': 0.3})"
+```
+Merges results from different operations.
+
+## Examples
+
+### Simple Query
+```python
+"topic -> memory.semantic(threshold=0.8) -> result"
+```
+Just finds semantically similar memories.
+
+### Complex Research
+```python
+memory_mapping = """
+    topic -> memory.semantic(threshold=0.9) |
+    memory.filter(recency='7d') |
+    memory.sort(by='relevance')
+    -> research_results
+"""
+```
+Finds recent, highly relevant memories.
+
+### Multi-path Search
+```python
+memory_mapping = """
+    topic -> memory.semantic(threshold=0.8) |
+    style -> memory.exact |
+    memory.combine(weights={'semantic': 0.6, 'exact': 0.4}) |
+    memory.filter(recency='24h')
+    -> final_results
+"""
+```
+This:
+1. Does semantic search on topic
+2. Does exact match on style
+3. Combines both results with weights
+4. Filters to last 24 hours
+
+### Real-world Example
+```python
+researcher = FlockAgent(
+    name="researcher",
+    input="query: str | Research query",
+    output="findings: str | Research findings",
+    memory_mapping="""
+        query -> memory.semantic(threshold=0.9, scope='global') |
+        memory.filter(recency='7d') |
+        memory.enrich(tools=['web_search']) |
+        memory.sort(by='relevance') |
+        memory.combine
+        -> findings
+    """
+)
+```
+
+## How It Works Internally
+
+1. **Parsing**:
+   ```python
+   mapping = "topic -> memory.semantic(0.8) | memory.filter(recency='7d')"
+   # Gets parsed into:
+   operations = [
+       SemanticOperation(threshold=0.8),
+       FilterOperation(recency='7d')
+   ]
+   ```
+
+2. **Execution**:
+   - Each operation is executed in sequence
+   - Results flow from one operation to the next
+   - Final results are returned
+
+3. **Error Handling**:
+   - Invalid operations are caught during parsing
+   - Runtime errors are caught during execution
+   - Clear error messages help debugging
+
+## Tips for Writing Mappings
+
+1. **Start Simple**
+   ```python
+   "query -> memory.semantic -> result"
+   ```
+
+2. **Add Refinements**
+   ```python
+   "query -> memory.semantic | memory.filter -> result"
+   ```
+
+3. **Fine-tune Parameters**
+   ```python
+   "query -> memory.semantic(threshold=0.9) | memory.filter(recency='7d') -> result"
+   ```
+
+4. **Complex Flows**
+   ```python
+   """
+   query -> memory.semantic |
+   memory.filter |
+   memory.sort |
+   memory.combine
+   -> result
+   """
+   ```