agentRamen

agentRamen

Apache-2.0 licensed. See the security policy and community code of conduct.

agentRamen indexes source structure and Git history, then retrieves task-relevant files and excerpts. It is local-first by default: each developer keeps a private SQLite index. Teams can optionally publish sanitized, commit-pinned snapshots to a centrally hosted, OIDC-protected read-only MCP service.

Quick start

Install agentRamen, then run it from the repository you want to explore:

python -m pip install agentramen

cd /path/to/your/repository agentramen init agentramen context "Add authentication" --budget 2000 agentramen impact src/auth.py

agentramen init creates the configuration, indexes the repository, and offers an optional GitHub Actions caller workflow. The index is stored locally in .agentramen/graph.db.

Try it in 30 seconds with examples/demo.sh. See the roadmap and contributing guide.

A minimal VS Code extension is also available.

What it can do

• Find task context: rank files using paths, symbols, imports, Git history, and optional local semantic similarity.
• Explain change impact: inspect dependencies, dependents, co-changes, hotspots, and file history.
• Map repository structure: explore architecture, export the graph, and query cached commit snapshots.
• Connect to coding agents: use local MCP stdio, the browser UI, or an optional authenticated centralized MCP service.
• Keep local indexes private: in local mode, the database and optional embeddings stay in each checkout; central mode transfers only an explicit sanitized snapshot to infrastructure you operate.

How it works

flowchart LR

repo[Working tree and Git history] --> indexer[Indexer and language analyzers] indexer --> db[(Local SQLite graph)] optional[Optional local embeddings] --> db task[Task or query] --> clients[CLI, MCP, or local HTTP] clients --> retrieve[Retrieval and graph queries] retrieve <--> db retrieve --> excerpts[Ranked files and source excerpts]

The default install uses the Python standard library and conservative analysis for other languages. Optional extras add Tree-sitter parsing, local semantic retrieval, and model-aware token counting.

How it compares

Optional extras

python -m pip install 'agentramen[treesitter]'

python -m pip install 'agentramen[semantic]' python -m pip install 'agentramen[tokenizer]' python -m pip install 'agentramen[central]'

The default install has no runtime dependencies. Tree-sitter, semantic embeddings, tokenizers, and the remote MCP service are opt-in. Semantic model setup may download weights on first use; inference runs locally.

agentramen init creates .agentramen.yml and a GitHub Actions caller workflow if they do not exist, then creates/updates .agentramen/graph.db. agentramen update and agentramen index incrementally refresh changed files. The database is ignored by Git.

In local mode, source excerpts and optional embeddings stay in .agentramen/graph.db. Central snapshot mode transfers indexed source that passes credential heuristics to your private central service; review your organization's data-handling requirements before enabling it.

Publishing releases

Configure a PyPI trusted publisher for palrajjp/agentRamen, using the .github/workflows/publish.yml workflow and the pypi environment. To publish a release, update the version in pyproject.toml and agentramen/__init__.py, create a matching v-prefixed Git tag, and publish a GitHub release for that tag. The workflow builds the distributions and publishes them to PyPI using OIDC.

Configuration

agentRamen reads the following fields from .agentramen.yml:

version: 1

indexing: incremental: true git: history: true co_changes: true history: commits: 100 semantic: enabled: false model: BAAI/bge-small-en-v1.5 context: default_budget: 2000 tokenizer_model: "" ignore:

• .env
• "*.pem"
• private/

indexing.incremental: false reparses every eligible file on each index. git.history: false removes stored commit, rename, and co-change history; enabling it later rebuilds the configured recent history. history.commits controls retained commits (1–100,000), and git.co_changes toggles co-change edges. context.default_budget is used by the CLI, MCP, and HTTP API when no budget is passed. Configuration is a dependency-free YAML subset; unsupported/malformed values are rejected with a setting-specific error. .agentramenignore patterns are added to, rather than replacing, the built-in and YAML ignore rules.

semantic.enabled: true opts into local embedding generation and semantic context ranking; install agentramen[semantic] first. semantic.model selects a FastEmbed model. agentramen[treesitter] opts into Tree-sitter-based parsing for supported non-Python languages; without it, or if a grammar is unavailable, agentRamen falls back to regex analysis.

context.tokenizer_model optionally selects a model supported by tiktoken for tokenizer-based context budgets; install agentramen[tokenizer] to use it. The tokenizer vocabulary may be downloaded and cached on first use, then counting runs locally. Leave it empty to use the dependency-free approximate character-based fallback. Context responses identify token_count_method (tiktoken or approximate) and the tokenizer model when configured. The reported total budgets the selected files, team memories, and path/digest/commit evidence together; per-file counts are provided as estimated_tokens.

Commands

agentramen init

agentramen index [--json] agentramen update [--json] agentramen status [--json] agentramen context "Add OAuth login" [--budget 2000] [--json] agentramen impact src/auth/AuthService.ts [--json] agentramen explain src/auth/AuthService.ts [--json] agentramen history src/auth/AuthService.ts [--json] agentramen search "auth login" [--limit 20] [--json] agentramen architecture [--at ] [--json] agentramen hotspots [--limit 20] [--json] agentramen changes [--limit 20] [--json] agentramen diff [--json] agentramen pr [--base origin/main] [--json] agentramen export [--at ] [--json] agentramen benchmark --files 10 1000 agentramen serve [--host 127.0.0.1] [--port 8765] agentramen mcp

Example context response:

{

"task": "Add authentication", "files": [ { "path": "src/auth_service.py", "language": "python", "symbols": ["AuthService"], "imports": [], "recent_change": "add authentication", "estimated_tokens": 18 } ], "token_budget": 2000, "files_avoided": 12, "confidence": "medium" }

Context includes source excerpts only when the file still matches its indexed hash and does not contain a detected credential pattern. Token counts use the configured model tokenizer when available; otherwise they are approximate character-based estimates, not tokenizer measurements or performance claims.

GitHub Actions

The workflow created by agentramen init calls the reusable workflow in this repository:

name: agentRamen

on: push: branches: ["**"] pull_request: workflow_dispatch: schedule:

• cron: "17 4 * * 1"

jobs: agentramen: uses: palrajjp/agentRamen/.github/workflows/index.yml@main

The reusable workflow fetches Git history, restores a cache, tests the installed package, indexes the checked-out revision, summarizes pull requests, and publishes the local SQLite artifact. Use a full-depth checkout when running the CLI outside this reusable workflow to retain history.

Use from gha-cd or another workflow

Call the reusable workflow before a deployment or agent job. Supplying task also creates a bounded JSON context artifact; the workflow does not send repository content to an AI provider.

jobs:

agentramen: uses: palrajjp/agentRamen/.github/workflows/index.yml@main with: task: "Trace the deployment workflow and identify rollback dependencies" token_budget: 1200

The artifact is named agentramen-context-${{ github.sha }}. A downstream job can fetch it and pass .agentramen-context/agentramen-context.json to its agent step:

- uses: actions/download-artifact@v4

with: name: agentramen-context-${{ github.sha }} path: .agentramen-context

The context budget defaults to 2000 if omitted. Treat the artifact like source code: it can contain excerpts and follows the repository's GitHub Actions access and retention policy.

Agent integrations

agentRamen's MCP server runs locally over stdio. Install agentRamen once on each developer machine, then add a portable .mcp.json at the repository root so VS Code Copilot and Claude Code can use the same configuration:

python -m pip install git+https://github.com/palrajjp/agentRamen.git

{

"mcpServers": { "agentramen": { "type": "stdio", "command": "age