Search Is Not Enough — Build AI Agents That Explore

Key Concepts

• Exploration-based Retrieval: Utilizing file system navigation and iterative file reading as a superior alternative to semantic search for specific knowledge base types (codebases, structured documents).
• Claude Code Inspiration: Mimicking Claude Code’s approach to knowledge retrieval through exploration rather than solely relying on vector search.
• GSD Framework: Employing the GSD (Get Done) framework for structured application development, acknowledging its benefits and drawbacks.
• Sub-Agent Architecture: Implementing a sub-agent system to delegate complex tasks like knowledge base exploration to specialized agents.
• Hybrid Retrieval Strategy: The potential for combining exploration-based and semantic search methods for optimal knowledge retrieval.

Building an AI-Powered Knowledge Agent: A Two-Part Development Process

This project details the construction of an AI-powered knowledge agent designed to overcome the limitations of traditional semantic search, particularly when applied to private knowledge bases like codebases, weekly reports, legal documents, and project artifacts. The build is inspired by Claude Code’s exploration-based retrieval method and utilizes the GSD (Get Done) framework for structured development.

Part 1: Foundation & Framework Introduction

The initial segment focused on the core concept of exploration versus search. Semantic search often struggles with structured data and codebases due to repetitive patterns (imports, exports, function definitions) leading to irrelevant results. Exploration, as demonstrated by Claude Code, involves iteratively navigating the file system, reading files, and forming theories based on the file structure – the file path itself providing valuable context. This approach is particularly effective when metadata is incomplete, inaccurate, or non-existent.

The project leverages the GSD framework, a leaner alternative to BMAD, OpenSpec, and SpecKit, emphasizing a phased workflow: Discuss/Brainstorm, Plan, Execute, and Verify. This framework generates detailed documentation (research.mmd, plans, roadmaps – exceeding 600 lines for a research plan) to track progress.

The build began with creating a custom knowledge base accessible via a web app, utilizing parameterized navigational tools (Glob, GP, Bash) instead of relying on pre-built APIs or MCPs. Key technical components include: Glob (file pattern matching), GP (grep – searching within files), Bash (shell commands), and tools for reading file contents. Claude Code’s iterative process was noted to involve 20-40 tool calls per problem. The limitations of context window size were acknowledged as a potential challenge. An AI-powered front-end design skill (skills.sh) was briefly experimented with for UI improvements.

Part 2: Implementation, Testing & Refinement

The second segment detailed the completion of phases 5-7 of the project, culminating in the end of the initial “epic”. These phases focused on integrating and testing core tools: GP (content search), Glob (filename search), Semantic Search (for initial document identification), Read Tool (retrieving document content), Tree Tool (displaying directory structure), and the Explorer Sub-Agent.

Numerous bugs were identified and addressed, including issues with document display, metadata visibility, front-end glitches (loading glimmer), and access control (global vs. user folders). The implementation of a sub-agent architecture was a key achievement, allowing the main agent to delegate complex research tasks to the Explorer sub-agent. An initial infinite loop issue within the Explorer sub-agent was resolved by limiting exploration rounds to eight.

Practical examples demonstrated the system’s capabilities, including searching for “coding standards” using Glob, implementing folder access controls, and using the Explorer sub-agent to summarize the entire knowledge base. The GSD framework was critically evaluated, highlighting its strengths (structured approach, thoroughness) and weaknesses (verbosity, sequential execution, limited parallelization). A shift towards a more test-driven development (TDD) approach was proposed for future phases.

Conclusion

This project successfully demonstrated the feasibility of building an AI-powered knowledge agent leveraging an exploration-based retrieval strategy inspired by Claude Code. While the GSD framework provided a structured development process, its limitations were also apparent. The implementation of a sub-agent architecture proved valuable for complex tasks, and the system’s ability to navigate and retrieve information from a private knowledge base was successfully validated. Future development will likely focus on incorporating TDD, addressing the GSD framework’s limitations, and potentially integrating a hybrid retrieval strategy combining exploration and semantic search for optimal performance.