> ## Documentation Index
> Fetch the complete documentation index at: https://docs-code.palyra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory, Retrieval, and Learning

<details>
  <summary>Relevant source files</summary>

  The following files were used as context for generating this wiki page:

  * apps/web/src/App.test.tsx
  * apps/web/src/App.tsx
  * apps/web/src/console/sections/MemorySection.tsx
  * apps/web/src/console/useConsoleAppState.tsx
  * apps/web/src/consoleApi.test.ts
  * apps/web/src/consoleApi.ts
  * crates/palyra-common/src/process\_runner\_input.rs
  * crates/palyra-daemon/src/application/instruction\_compiler.rs
  * crates/palyra-daemon/src/application/learning.rs
  * crates/palyra-daemon/src/application/memory.rs
  * crates/palyra-daemon/src/application/recall.rs
  * crates/palyra-daemon/src/application/service\_authorization.rs
  * crates/palyra-daemon/src/application/tool\_registry/builtin.rs
  * crates/palyra-daemon/src/application/tool\_registry/tests.rs
  * crates/palyra-daemon/src/application/tool\_runtime/memory.rs
  * crates/palyra-daemon/src/gateway/tests.rs
  * crates/palyra-daemon/src/sandbox\_runner.rs
  * crates/palyra-daemon/src/transport/grpc/services/memory/service.rs
  * crates/palyra-daemon/src/transport/http/handlers/console/memory.rs
  * schemas/proto/palyra/v1/memory.proto
</details>

The Palyra memory subsystem provides agents with durable storage, multi-modal retrieval, and a post-run reflection pipeline. It bridges the gap between transient session state and long-term knowledge by managing the lifecycle of facts, preferences, and procedures across different scopes.

## 4.1. Memory Lifecycle and Storage

The memory system operates on a tiered scope model: **Principal** (user-wide), **Channel** (platform-specific), and **Session** (current conversation) [crates/palyra-daemon/src/application/memory.rs#11-16](http://crates/palyra-daemon/src/application/memory.rs#11-16). All memory operations are mediated by the `MemoryLifecycleProvider`, which handles ingestion through a pipeline of classification, deduplication, and redaction [crates/palyra-daemon/src/application/memory.rs#4-9](http://crates/palyra-daemon/src/application/memory.rs#4-9).

Durable memory items are stored in the journal and exposed via the gRPC `MemoryService` [crates/palyra-daemon/src/transport/grpc/services/memory/service.rs](). The system enforces strict visibility: channel-scoped items are invisible without matching channel context, and all text is redacted before being returned to models to prevent credential leakage [crates/palyra-daemon/src/application/memory.rs#107-138](http://crates/palyra-daemon/src/application/memory.rs#107-138).

**Key Components:**

* **MemoryLifecycleProvider**: Manages the `retain`/`delete`/`replace` logic [crates/palyra-daemon/src/application/memory.rs#41](http://crates/palyra-daemon/src/application/memory.rs#41).
* **Write Classification**: Categorizes incoming memories (e.g., `manual`, `summary`, `import`) and assigns sensitivity levels [crates/palyra-daemon/src/application/memory.rs#72-91](http://crates/palyra-daemon/src/application/memory.rs#72-91).
* **Redaction Pipeline**: Uses `redact_memory_text_for_output` to sanitize content before model consumption [crates/palyra-daemon/src/application/memory.rs#161-170](http://crates/palyra-daemon/src/application/memory.rs#161-170).

For details, see [Memory Lifecycle and Storage](/memory_retrieval_and_learning/memory_lifecycle_and_storage).

**Sources:** [crates/palyra-daemon/src/application/memory.rs#1-170](http://crates/palyra-daemon/src/application/memory.rs#1-170), [crates/palyra-daemon/src/transport/grpc/services/memory/service.rs]()

## 4.2. Retrieval-Augmented Generation (RAG) and Recall

Retrieval is governed by the `RecallPlan`, which coordinates hybrid search across multiple indices. The `InstructionCompiler` integrates retrieved context into the model's system prompt, ensuring the agent is aware of the trust posture of the provided data [crates/palyra-daemon/src/application/instruction\_compiler.rs#28-38](http://crates/palyra-daemon/src/application/instruction_compiler.rs#28-38).

### Hybrid Search Architecture

Palyra combines lexical search (FTS5), vector embeddings, and recency scoring to rank results. The `palyra.memory.search` tool allows agents to query their own memory or indexed workspace documents [crates/palyra-daemon/src/application/tool\_registry/builtin.rs#105-139](http://crates/palyra-daemon/src/application/tool_registry/builtin.rs#105-139).

Memory Retrieval Mapping

```mermaid theme={null}
graph TD
    subgraph "Natural Language Space"
        UserQuery["User Query / Intent"]
        RecallPlan["RecallPlan (Expanded Queries)"]
    end

    subgraph "Code Entity Space"
        RecallService["application::recall::RecallService"]
        HybridSearch["retrieval::HybridSearchProvider"]
        FTS5["SQLite FTS5 (Lexical)"]
        VectorDB["Vector Index (Semantic)"]
        MemoryTool["palyra.memory.search (builtin.rs)"]
    end

    UserQuery --> RecallService
    RecallService --> RecallPlan
    RecallPlan --> HybridSearch
    HybridSearch --> FTS5
    HybridSearch --> VectorDB
    MemoryTool --> RecallService
```

**Sources:** [crates/palyra-daemon/src/application/recall.rs](), [crates/palyra-daemon/src/application/instruction\_compiler.rs#1-87](http://crates/palyra-daemon/src/application/instruction_compiler.rs#1-87), [crates/palyra-daemon/src/application/tool\_registry/builtin.rs#105-140](http://crates/palyra-daemon/src/application/tool_registry/builtin.rs#105-140)

For details, see [Retrieval-Augmented Generation (RAG) and Recall](/memory_retrieval_and_learning/retrieval-augmented_generation_rag_and_recall).

## 4.3. Post-Run Learning and Reflection Pipeline

The learning subsystem performs asynchronous reflection on completed runs to extract reusable knowledge. It generates `LearningCandidate` objects, which can be durable facts, user preferences, or "patch skills" (suggested improvements to existing tools) [crates/palyra-daemon/src/application/learning.rs]().

### Learning Ingestion Flow

The `Learning Curator` audits these candidates, applying sampling heuristics to prioritize high-value insights. Candidates remain in a pending state until an operator approves them via the Web Console [apps/web/src/console/sections/MemorySection.tsx#71-112](http://apps/web/src/console/sections/MemorySection.tsx#71-112).

Memory Learning Pipeline

```mermaid theme={null}
graph LR
    subgraph "Run Execution"
        RunTape["JournalStore (Tape)"]
    end

    subgraph "Post-Run Learning (application::learning)"
        Reflector["LearningReflector"]
        Candidate["LearningCandidate (Kind: durable_fact, preference, patch_skill)"]
        Curator["LearningCurator (Audit & Heuristics)"]
    end

    subgraph "Human-in-the-loop (Web Console)"
        UI["MemorySection.tsx"]
        Approval["MemoryItemLifecycleUpdateRequest"]
    end

    RunTape --> Reflector
    Reflector --> Candidate
    Candidate --> Curator
    Curator --> UI
    UI --> Approval
    Approval --> MemoryLifecycleProvider["application::memory"]
```

**Sources:** [crates/palyra-daemon/src/application/learning.rs](), [apps/web/src/console/sections/MemorySection.tsx#131-190](http://apps/web/src/console/sections/MemorySection.tsx#131-190), [crates/palyra-daemon/src/application/memory.rs#1-9](http://crates/palyra-daemon/src/application/memory.rs#1-9)

For details, see [Post-Run Learning and Reflection Pipeline](/memory_retrieval_and_learning/post-run_learning_and_reflection_pipeline).

## Child Pages

* [Memory Lifecycle and Storage](/memory_retrieval_and_learning/memory_lifecycle_and_storage)
* [Retrieval-Augmented Generation (RAG) and Recall](/memory_retrieval_and_learning/retrieval-augmented_generation_rag_and_recall)
* [Post-Run Learning and Reflection Pipeline](/memory_retrieval_and_learning/post-run_learning_and_reflection_pipeline)