Add session state: save/load working state between agent instances

- New 'session' memory type for capturing in-progress work, blockers, decisions
- save_session() supersedes previous session automatically
- load_session() returns the most recent state for the project
- MCP tools: save_session, load_session
- CLI: agentmem save-session, agentmem load-session
- Prevents cold-start problem when context compresses or conversations end

Author: Thezenmonster

agentmem/cli.py

@@ -187,6 +187,31 @@ def stats(ctx):
     mem.close()
 
 
+@main.command("save-session")
+@click.argument("summary")
+@click.pass_context
+def save_session(ctx, summary):
+    """Save session state for the next agent instance."""
+    mem = _get_mem(ctx)
+    record = mem.save_session(summary)
+    click.echo(f"Session saved: {record.id}")
+    mem.close()
+
+
+@main.command("load-session")
+@click.pass_context
+def load_session(ctx):
+    """Load the most recent session state."""
+    mem = _get_mem(ctx)
+    record = mem.load_session()
+    if record:
+        click.echo(f"Last session ({record.created_at}):\n")
+        click.echo(record.content)
+    else:
+        click.echo("No previous session found.")
+    mem.close()
+
+
 @main.command()
 @click.pass_context
 def serve(ctx):

agentmem/core.py

@@ -203,6 +203,51 @@ def stats(self) -> dict:
             "db_size_kb": round(db_size / 1024, 1),
         }
 
+    def save_session(self, summary: str, tags: list[str] | None = None) -> MemoryRecord:
+        """Save current session state. Supersedes any previous session for this project.
+
+        Call this before a conversation ends or when context is about to compress.
+        The summary should capture: what's in progress, what's blocked, what's done,
+        and any decisions made this session.
+        """
+        # Find and supersede the previous session
+        prev = self._conn.execute(
+            "SELECT id FROM memories WHERE type = 'session' AND project = ? "
+            "ORDER BY created_at DESC LIMIT 1",
+            (self.project,),
+        ).fetchone()
+
+        supersedes = prev["id"] if prev else ""
+
+        return self.add(
+            type="session",
+            title=f"Session state — {self.project or 'default'}",
+            content=summary,
+            tags=tags or ["session", "state"],
+            source="session",
+            supersedes=supersedes,
+        )
+
+    def load_session(self) -> MemoryRecord | None:
+        """Load the most recent session state for this project.
+
+        Call this at the start of a conversation to pick up where the last instance left off.
+        """
+        row = self._conn.execute(
+            "SELECT * FROM memories WHERE type = 'session' AND project = ? "
+            "ORDER BY created_at DESC LIMIT 1",
+            (self.project,),
+        ).fetchone()
+        if not row:
+            return None
+
+        self._conn.execute(
+            "UPDATE memories SET accessed_at = ?, access_count = access_count + 1 WHERE id = ?",
+            (_now(), row["id"]),
+        )
+        self._conn.commit()
+        return _row_to_record(row)
+
     def close(self):
         self._conn.close()
 

agentmem/mcp_server.py

@@ -107,6 +107,26 @@ async def list_tools():
                     },
                 },
             ),
+            Tool(
+                name="save_session",
+                description="Save current session state before conversation ends or context compresses. Capture: what's in progress, what's blocked, what's done, decisions made. The next agent instance loads this automatically.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {
+                        "summary": {"type": "string", "description": "Full session state: in-progress work, blocked items, completed items, key decisions"},
+                        "tags": {"type": "array", "items": {"type": "string"}, "default": ["session", "state"]},
+                    },
+                    "required": ["summary"],
+                },
+            ),
+            Tool(
+                name="load_session",
+                description="Load the most recent session state. Call this at the start of a conversation to pick up where the last instance left off.",
+                inputSchema={
+                    "type": "object",
+                    "properties": {},
+                },
+            ),
         ]
 
     @server.call_tool()
@@ -166,6 +186,19 @@ async def call_tool(name: str, arguments: dict):
             lines = [f"[{r.type}] {r.title} (id: {r.id})" for r in records]
             return [TextContent(type="text", text="\n".join(lines))]
 
+        elif name == "save_session":
+            record = mem.save_session(
+                summary=arguments["summary"],
+                tags=arguments.get("tags", ["session", "state"]),
+            )
+            return [TextContent(type="text", text=f"Session saved: {record.id}\n{record.content[:200]}...")]
+
+        elif name == "load_session":
+            record = mem.load_session()
+            if record:
+                return [TextContent(type="text", text=f"Last session ({record.created_at}):\n\n{record.content}")]
+            return [TextContent(type="text", text="No previous session found.")]
+
         return [TextContent(type="text", text=f"Unknown tool: {name}")]
 
     import asyncio

agentmem/models.py

@@ -4,7 +4,7 @@
 
 from dataclasses import dataclass, field
 
-MEMORY_TYPES = ("setting", "bug", "decision", "procedure", "context", "feedback")
+MEMORY_TYPES = ("setting", "bug", "decision", "procedure", "context", "feedback", "session")
 
 
 @dataclass