Skip to content

feat(mcp): expose mem_list_projects tool — CLI has projects list but MCP doesn't expose it #675

Description

@developerFer

Pre-flight Checks

  • I have searched existing issues and this is not a duplicate
  • I understand this issue needs status:approved before a PR can be opened

Problem Description

The Engram CLI already has engram projects list which returns all known project names. However, this capability is NOT exposed as an MCP tool. The 20 MCP tools available to agents include mem_search, mem_context, mem_current_project, etc. — but nothing that lets an agent ask "what projects does this user have?"

This means agents cannot discover which projects exist before searching memories. They must either already know the project name (from the user's message or cwd) or search without a project filter and hope keywords match. In practice, this causes agents to miss relevant memories at session start.

Environment:

  • Engram version: latest (MCP server, stdio transport)
  • Agent client: OpenCode
  • Platform: Windows (amd64)

Reproducible commands:

engram projects list
→ returns: project-a, project-b, project-c

This works from CLI. But from an agent session, the only way to discover projects is:

mem_current_project → { project: "\\", available_projects: null }
mem_search(query: "anything", project: "\\") → empty

The agent has no MCP tool to list all projects. mem_current_project returns the current project and alternatives if ambiguous, but never a full list of all projects known to Engram.

Observed behavior (current — agent cannot discover all projects):

[Session starts in a directory not matching any known project]
mem_current_project → { project: "\\", available_projects: null }
[Agent searches Engram with generic keywords, finds nothing, proceeds blind]
[Meanwhile, user has 3+ projects with memories in Engram, all undiscoverable]

Expected behavior (proposed — agent can discover all projects):

mem_list_projects → ["project-a", "project-b", "project-c"]
[Agent scopes subsequent mem_search/mem_context to the correct project]

Proposed Solution

Expose engram projects list (or equivalent query) as an MCP tool:

mem_list_projects → ["project-a", "project-b", "project-c"]

The underlying SQL query already exists (engram projects list works from CLI). This is purely an MCP exposure gap.

Affected Area

MCP server (tool exposure)

Alternatives Considered

  • Use mem_current_project only: returns the current project and ambiguous alternatives, but never a full project list. Useful for session-start scoping but insufficient for cross-project recall.
  • Script it via bash calling engram projects list: fragile, depends on engram being in PATH, not available to all agent clients.
  • Do nothing: agents continue to miss context at session start.

Additional Context

Related to gentle-ai#1903 (proactive Engram search fails because agent doesn't discover projects). mem_current_project covers the single-project and ambiguous cases, but mem_list_projects is needed for the separate use case of explicit cross-project recall.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions