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

# Memory System

> Persistent, evolving memory that helps your AI agents remember and learn over time

## Overview

Junis provides a **hierarchical memory system** that enables AI agents to remember users across conversations. Unlike traditional chatbots that forget everything after each session, Junis agents build a growing understanding of each user over time.

> Your AI agents don't just respond — they remember, learn, and evolve with every conversation.

<Info>
  **Automatic**: Memory collection and consolidation happen automatically. No manual setup required — just start chatting.
</Info>

***

## How It Works

<CardGroup cols={2}>
  <Card title="Remembers Conversations" icon="brain">
    Key information from every conversation is captured and stored automatically.
  </Card>

  <Card title="Learns Over Time" icon="chart-line">
    Daily memories are consolidated into monthly, quarterly, and yearly summaries by AI.
  </Card>

  <Card title="Personalized Responses" icon="user">
    Agents use stored memories to provide contextual, personalized interactions for each user.
  </Card>

  <Card title="User-Controlled" icon="shield-check">
    Users can view and update their own profile. Memory is scoped per-user with full privacy.
  </Card>
</CardGroup>

***

## Memory Architecture

Junis organizes memory into a **hierarchical tier system**, inspired by how human memory works — from detailed daily notes to high-level life narratives:

### Memory Tiers

| Tier                  | Description                                       | Updated                          |
| --------------------- | ------------------------------------------------- | -------------------------------- |
| **User Profile**      | Name, preferences, communication style, expertise | Anytime (by agent or user)       |
| **Eternal Memory**    | Core truths and permanent preferences             | Anytime (by agent)               |
| **Daily Memory**      | Conversation summaries per day                    | After each conversation          |
| **Monthly Summary**   | Consolidated patterns and themes                  | Automatically, 1st of each month |
| **Quarterly Summary** | Growth trajectories and milestones                | Automatically, every quarter     |
| **Yearly Narrative**  | Autobiographical narrative of the year            | Automatically, January 1st       |

### Consolidation Flow

```mermaid theme={null}
graph LR
    Conv[Conversations] -->|After each chat| Daily[Daily Memory]
    Daily -->|Monthly AI review| Monthly[Monthly Summary]
    Monthly -->|Quarterly AI review| Quarterly[Quarterly Summary]
    Quarterly -->|Yearly AI review| Yearly[Yearly Narrative]
    Conv -->|Key insights extracted| Eternal[Eternal Memory]
```

<Note>
  **AI-Powered Consolidation**: An AI model reviews and consolidates memories at each tier, preserving important patterns while letting trivial details naturally fade — mimicking how human memory works.
</Note>

***

## What Gets Remembered

### Automatic Memory (No Action Needed)

The system automatically captures:

* **Conversation summaries** from each session
* **User preferences** mentioned naturally in conversation
* **Key decisions** and outcomes
* **Recurring topics** and interests

### Explicit Memory Commands

Users can explicitly ask agents to remember things:

```
"Remember that I prefer concise responses."
"Don't forget that our quarterly reviews are on Fridays."
"Always format reports with bullet points for me."
```

Agents store these as **Eternal Memory** — persistent facts that are always available.

### User Profile Updates

When agents learn about users, they automatically update the profile:

```
"My name is Sarah and I'm a marketing director."
→ Agent updates User Profile with name and role

"I prefer Korean for internal docs and English for client-facing work."
→ Agent updates communication preferences
```

***

## Memory in Action

### How Agents Use Memory

Every time an agent starts a conversation, it automatically loads the user's memory context:

1. **User Profile** — Who the user is
2. **Eternal Memory** — Permanent preferences and instructions
3. **Recent Daily Memories** — What happened in recent conversations
4. **Latest Summaries** — Monthly/quarterly/yearly patterns

This context is automatically injected into the agent's awareness, so it can reference past interactions naturally.

### Example Interaction

```
Day 1:
User: "I'm working on the Q4 marketing campaign for product launch."
Agent: [Stores in daily memory]

Day 5:
User: "How's the project going?"
Agent: "Based on our conversation earlier this week about the
Q4 marketing campaign for the product launch, here's where
we can pick up..."
→ Agent references past context without being asked
```

### Cross-Session Continuity

```
Week 1: User discusses project goals and timelines
Week 2: User mentions team members and responsibilities
Week 3: User provides budget details

Monthly Summary (auto-generated):
"User is managing a Q4 product launch campaign with a team of 5.
Key priorities: timeline adherence, budget of $50K, and
cross-department coordination."
```

***

## Managing Memory

### View Your Memory

You can ask any agent to show your stored memories:

```
"Show me my profile."
→ Agent displays your current User Profile

"What do you remember about me?"
→ Agent reads and summarizes your memory context
```

### Update Your Profile

Ask an agent to update your information:

```
"Update my profile: I've moved to the product team."
→ Agent updates your role

"Remove the note about my old email address."
→ Agent reads eternal memory, removes the entry, saves
```

### Memory via API & MCP

Access memory programmatically through the [Junis Magic](/guides/junis-magic) MCP tools:

| Tool                    | Purpose                          |
| ----------------------- | -------------------------------- |
| `get_memory_directory`  | List all memory files for a user |
| `get_memory_content`    | Read specific memory content     |
| `update_memory_content` | Update the user profile          |

***

## Memory Tools for Agents

Junis automatically equips all orchestrator agents with two memory tools:

<Tabs>
  <Tab title="User Memory Tool">
    ### `update_user_memory`

    Read or update the user's profile.

    **When agents use this tool**:

    * User shares their name, role, or job title
    * Communication preferences are revealed
    * Professional expertise becomes apparent
    * User explicitly asks to see their profile

    **Actions**: `read` (view profile), `update` (save changes)
  </Tab>

  <Tab title="Eternal Memory Tool">
    ### `save_to_eternal_memory`

    Store permanent facts and preferences.

    **When agents use this tool**:

    * User says "remember this" or "don't forget"
    * User wants a standing instruction ("always do it this way")
    * User wants to edit or delete existing memories

    **Actions**: `read` (view), `add` (append), `update` (replace)
  </Tab>
</Tabs>

<Info>
  **Automatic**: These tools are available to all orchestrator agents by default. No configuration needed.
</Info>

***

## Privacy & Security

<AccordionGroup>
  <Accordion title="Per-User Isolation" icon="lock">
    Memory is strictly scoped to individual users. No user can access another user's memories, even within the same organization.
  </Accordion>

  <Accordion title="Organization Boundaries" icon="building">
    Memory is completely isolated between organizations. Switching organizations means working with a separate memory context.
  </Accordion>

  <Accordion title="User Control" icon="user-shield">
    Users can view, update, and manage their own memory at any time. Agents are designed to never store sensitive information like passwords, financial data, or API keys in memory.
  </Accordion>

  <Accordion title="Subscription-Based Processing" icon="credit-card">
    Memory consolidation (monthly/quarterly/yearly) is processed only for users with active subscriptions, ensuring fair resource usage.
  </Accordion>
</AccordionGroup>

***

## Related Guides

<CardGroup cols={2}>
  <Card title="Soul & Identity" icon="sparkles" href="/guides/soul-identity">
    Define your AI's personality (organization-level)
  </Card>

  <Card title="Agent System" icon="robot" href="/getting-started/agent-system">
    Learn about agent types and orchestration
  </Card>

  <Card title="Junis Magic" icon="wand-magic-sparkles" href="/guides/junis-magic">
    Manage memory via MCP tools
  </Card>

  <Card title="Billing & Credits" icon="coins" href="/guides/billing/credits">
    Understand usage costs
  </Card>
</CardGroup>

***

<Note>
  **Need Help?** Contact us at [contact@junis.ai](mailto:contact@junis.ai) for questions about the memory system.
</Note>