Project Memory (Session Memory)

Aster can record terminal work so the next Agent can query a project's past process without another explanation. It is off by default; enable Session Memory Recording under Settings → Agents.

• Modes: Off, Recording, and Incognito. Off/Incognito both write nothing; Incognito signals a temporary pause. Recording captures commands, exit codes, output excerpts, CWD, Agent state, and git branch/commit. Full command output is in separate files, with excerpts in the database. Empty sessions without commands or Agent participation are neither recorded nor listed in History.
• Excluded directories/commands are blocked at event creation, not recorded then deleted. Excluded-command output is excluded too. Common secrets are masked before writes using the Send to Chat rules. An always-active, nonremovable baseline excludes ~/.ssh, ~/.gnupg, ~/.aws, ~/.kube, ~/.password-store, and commands op, vault, pass, gpg, security; your exclusions add to it.
• Data stays in ~/Library/Application Support/Aster/Memory/, with directories 0700 and files 0600. Settings can show usage, open the folder, or clear all records. Memory and diagnostics are independent, with distinct masking rules and no shared files.
• Extraction derives reusable conclusions (problem, root cause, failed attempts, solution) when a Shell exits or a tab/Pane closes. Sessions missed on app quit/crash are processed on next launch. Local rule-based extraction always runs without network. Optional CLI Agent extraction invokes your installed Agent CLI and sends the session summary to that Agent's cloud service. It is off by default, asks on first enable, and offers an exact outgoing-content preview. Unavailable CLI, timeout, or parse failure falls back to rules without losing recorded facts.
• History: Outline's lower area groups timelines by session, including commands/exit codes, expandable output, tools, file reads/writes, and git snapshots. Supplemental Agent-transcript entries are labeled separately. History gives extracted project Memory with pinned entries first and a browser-management entry.
• Tasks and Memory management: the palette (⇧⌘P) offers Browse Session Memory, create Task, assign current session to Task, and continue Task. Tasks can link multiple sessions across Agents. The Memory browser is a separate panel window that can remain open beside terminal work; closing returns focus naturally. Search, source backlinks, pin, disable, and delete are available. Disabled Memory is invisible to Agent retrieval.
• Pin conclusions: pinned architecture decisions/conventions always accompany project context, bypassing retrieval ranking.
• Retention: raw events/output older than 90 days are cleaned at session end. Extracted Memory and session summaries remain indefinitely.
• Agent access log: Context records show each MCP query's time, query, returned Memory count, and approximate tokens.

Give Agents Access through MCP

The bundled local aster-memory-mcp server lets MCP-capable Agents query the same memory. It opens the database read-only and works even while Aster is not running.

Tools: search_memory (Memory/commands), get_project_context (overview, always pinned first), get_session (full timeline), get_related_history (files/keywords), get_task (details/list), and get_recent_commands.

Uninformative broad queries return empty instead of irrelevant material. If nothing matches the current project, search widens to other projects with explicit origin labels. Historical text has a non-instruction declaration and structural sanitization; instruction-shaped output is not executed as commands.

Registration is under Settings → Agents → Project Memory MCP, after recording/extraction choices:

• The current project comes from the active tab of the most recently active workspace window; MCP registration is per project.
• Claude Code writes the project's .mcp.json, managing only aster-memory and preserving other servers. Correct registration shows disabled Installed; stale paths offer repair, and Remove is available.
• Codex offers a copyable snippet. Aster does not edit ~/.codex/config.toml for you.
• Permission, symlink, size, or JSON errors reading .mcp.json are shown with installation disabled, rather than pretending it is unregistered.