Skip to content

Releases: osick/archaeocode

Release list

archaeocode v0.4.0 — The Site Archive

archaeocode v0.4.0 — The Site Archive Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 17 Sep 16:44
v0.4.0
f4ead19
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

archaeocode — automated software archaeology. Release 0.4.0, "The Site Archive".

Until now every dig ended with a JSON report and amnesia. This release gives archaeocode a memory: a persistent, queryable knowledge base built on LightRAG (GraphRAG: knowledge graph + vector retrieval). Files, AST entities, dependency edges, and user stories become a graph you can interrogate from the terminal, from any MCP-capable agent, or as an Obsidian-style wiki.

Highlights

  • Knowledge base workflow step (archaeo --knowledge-base): files, classes, functions, methods, import/call edges with circular-dependency markers, and user stories are written into the graph without a single LLM call. Exact, cheap, idempotent.
  • Business vocabulary on demand (--kb-extract): with an API key, LightRAG's entity/relation extraction mines the code for customers, tariffs, invoice runs and files them next to the technical entities.
  • archaeo-kb CLI: query, retrieve, context, graph, stats, add, wiki. Only query needs an LLM; everything else works offline.
  • knowledge-base MCP server with kb_query, kb_retrieve, kb_context, kb_graph, kb_stats, kb_add_documents, kb_export_wiki, so Claude Desktop, Claude Code, or your own agent can ask the archive instead of re-reading the code.
  • Obsidian-compatible wiki export (--kb-wiki DIR): one cross-linked page per file, function, dependency, and user story.
  • Scale by configuration: NetworkX + nano-vectordb on a laptop with zero infrastructure; Neo4j / PostgreSQL+pgvector / Qdrant / Milvus / Redis for estates the size of a bank; workspaces keep several systems apart in one back-end. Embeddings via sentence-transformers (local, default), OpenAI, or Ollama; LLM via Anthropic, OpenAI, or Ollama.
  • Air-gapped mode: KB_TOKENIZER=bytes and KB_EMBEDDING_PROVIDER=hashing run the whole pipeline with no network. The new test suite runs this way in CI.
  • Docs, retold as a dig: README field guide, quickstart, and the knowledge-management decision record explaining why GraphRAG over an LLM wiki or vanilla RAG, and why LightRAG over Microsoft GraphRAG, Cognee, Graphiti, and neo4j-graphrag.

Getting started

git clone https://github.com/osick/archaeocode.git
cd archaeocode
pip install -r requirements.txt
pip install -e .            # puts archaeo and archaeo-kb on your PATH
cp .env.example .env        # add ANTHROPIC_API_KEY for user stories and answers

archaeo --source sample_data/cobol --source-lang cobol --knowledge-base --kb-wiki ./wiki
archaeo-kb retrieve "PAYMENT" --mode local
archaeo-kb query "Which programs touch the customer master file?"

Changed

  • AST entities now carry file_path, so classes, functions, and methods link to their file.
  • requirements.txt adds lightrag-hku.

Full change history: docs/CHANGELOG.md

Assets 2
Loading

archaeocode v0.3.0

archaeocode v0.3.0

Choose a tag to compare

View all tags
@osick osick released this 28 Aug 20:15
v0.3.0
0610665

archaeocode — automated software archaeology. First public release.

Point archaeocode at a legacy codebase (COBOL, Smalltalk, Fortran, Pascal, Java, Python, JS/TS) and get back business-readable user stories, a dependency map with cycle detection, and structural AST analysis — excavated from code whose authors are long gone, orchestrated by LangGraph agents over MCP tool servers.

Highlights

  • User stories from code: an LLM turns each source file's business logic into user stories with roles, capabilities, benefits, acceptance criteria, priority, and confidence scores — a migration backlog, not just diagrams
  • Legacy-first parsing: tree-sitter based AST analysis, including custom Smalltalk grammars (standard + Cincom/VisualWorks); works on code with no usable git history
  • MCP architecture: static analysis, graph DB, and RAG pipeline are reusable Model Context Protocol servers
  • Observable: optional LangSmith tracing of every workflow run
  • CI: tested on Python 3.10–3.12; compatible with MCP SDK 1.x and 2.x

Getting started

git clone https://github.com/osick/archaeocode.git
cd archaeocode
pip install -r requirements.txt
cp .env.example .env   # add ANTHROPIC_API_KEY for user stories

./archaeo --source sample_data/cobol --source-lang cobol --target-lang java
# or install the CLI onto your PATH:
pip install -e . && archaeo --source sample_data/cobol --source-lang cobol --target-lang java

Full change history: docs/CHANGELOG.md

Loading