Offline Codebase Memory for Gemma 4

MICode Tutor compiles a repository into a portable .mic Machine-Interpretable Code memory file, then lets local Gemma 4 read that memory for repo Q&A, learning, test generation, and safe patch planning.

AI coding tutors should work without the cloud.

Modern AI coding assistants are powerful, but they often assume:

• reliable cloud access,
• paid API keys,
• and permission to upload private code.

That leaves many students, independent builders, open-source maintainers, and privacy-sensitive teams behind.

MICode Tutor takes a local-first approach:

repo
→ .mic memory artifact
→ symbol-aware retrieval
→ auditable context pack
→ local Gemma 4 via Ollama or llama.cpp

Gemma does not blindly inspect the entire repository. MICSDK prepares a compact evidence pack first. Gemma reasons over that evidence.

MICode Tutor is not a prompt wrapper that dumps source code into an LLM.

When you run:

mic compile examples/edu_auth_service --out edu_auth_service.mic

MICSDK builds a .mic memory file containing:

• file cards,
• symbol cards,
• classes, functions, and methods,
• imports and exports,
• line ranges,
• test references,
• call relations,
• evidence snippets,
• lightweight state tokens,
• repo capabilities,
• and agent recipes for Q&A, testing, and patch planning.

You can inspect it locally:

mic inspect edu_auth_service.mic

You can search it without calling any model:

mic search "where is JWT authentication verified?" --memory edu_auth_service.mic

You can see exactly what Gemma will receive:

mic pack "where is JWT verified?" \
  --memory edu_auth_service.mic \
  --budget 500 \
  --top-k 3 \
  --out context_jwt.md

Then you can ask local Gemma:

mic ask "where is JWT verified?" \
  --memory edu_auth_service.mic \
  --backend ollama \
  --model gemma4:latest

The included demo repository is an educational Python authentication service:

examples/edu_auth_service/
  app/
    main.py
    config.py
    auth/
      token.py
      password.py
      routes.py
    middleware/
      auth_required.py
    security/
      rate_limit.py
    db/
      users.py
  tests/
    test_auth.py
    test_config.py

The demo supports questions such as:

mic ask "where is JWT verified?" --memory edu_auth_service.mic --backend ollama --model gemma4:latest

mic ask "explain this repo to a beginner. Give a 5-step learning path." \
  --memory edu_auth_service.mic \
  --backend ollama \
  --model gemma4:latest

mic test "write a pytest for expired refresh tokens." \
  --memory edu_auth_service.mic \
  --backend ollama \
  --model gemma4:latest

mic plan "add Redis-based rate limiting to login. What files change and what tests are needed?" \
  --memory edu_auth_service.mic \
  --backend ollama \
  --model gemma4:latest

git clone https://github.com/<your-org>/micode-tutor.git
cd micode-tutor
pip install -e .

mic demo

mic compile examples/edu_auth_service --out edu_auth_service.mic

mic inspect edu_auth_service.mic

Expected output includes repository metadata such as:

Files: 17
Symbols: 355
Relations: 46
State tokens: 372

mic search "where is JWT authentication verified?" --memory edu_auth_service.mic

mic ask "where is JWT verified?" \
  --memory edu_auth_service.mic \
  --backend ollama \
  --model gemma4:latest

MICode Tutor supports multiple local Gemma runtimes.

Ollama is the easiest way to run Gemma locally.

mic ask "where is JWT verified?" \
  --memory edu_auth_service.mic \
  --backend ollama \
  --model gemma4:latest

If you already have a local GGUF model, MICode Tutor can create an Ollama model from it:

mic backend ollama-start

mic backend ollama-create \
  --gguf /path/to/gemma4-e4b-q4_k_m.gguf \
  --name gemma4:latest

mic backend ollama-test --model gemma4:latest

(Certainly,we support llama.cpp backend)

This supports offline or USB-delivered model artifacts.

llama.cpp is a lower-level GGUF inference runtime suitable for resource-constrained environments.

MICode Tutor includes a guided backend setup layer:

mic backend install llamacpp
mic backend llamacpp-start --gguf /path/to/model.gguf
mic backend llamacpp-test

Then:

```bash
mic ask "where is JWT verified?" \
  --memory edu_auth_service.mic \
  --backend llamacpp \
  --model gemma4

Check local runtime status:

mic backend doctor

This reports GPU availability, Ollama status, llama.cpp build status, and local GGUF model files.

They serve different deployment needs.

MICode Tutor uses the same .mic memory and context pack with either backend.

MICode Tutor is designed as a human-in-the-loop coding tutor.

It does not automatically mutate your repository.

Safety features:

• local .mic memory file,
• no cloud API required,
• no code upload,
• inspectable memory,
• auditable context packs,
• evidence citations with file paths and line ranges,
• patch planning instead of automatic edits,
• test generation for human review.

Example:

mic pack "where is JWT verified?" \
  --memory edu_auth_service.mic \
  --out context_jwt.md

This shows exactly what context Gemma receives.

# Compile repo into .mic memory
mic compile examples/edu_auth_service --out edu_auth_service.mic

# Inspect memory
mic inspect edu_auth_service.mic

# Local search without LLM
mic search "where is JWT authentication verified?" --memory edu_auth_service.mic

# Build an auditable context pack
mic pack "write tests for expired refresh tokens" --memory edu_auth_service.mic

# Ask local Gemma 4
mic ask "explain the auth flow" --memory edu_auth_service.mic --backend ollama --model gemma4:latest

# Generate tests
mic test "write tests for expired refresh tokens" --memory edu_auth_service.mic --backend ollama --model gemma4:latest

# Generate a safe patch plan
mic plan "add Redis-based rate limiting to login" --memory edu_auth_service.mic --backend ollama --model gemma4:latest

# Backend setup
mic backend doctor
mic backend ollama-start
mic backend ollama-create --gguf /path/to/model.gguf --name gemma4:latest
mic backend llamacpp-build
mic backend llamacpp-start --gguf /path/to/model.gguf

┌────────────────────┐
│ Source Repository  │
└─────────┬──────────┘
          │
          ▼
┌────────────────────┐
│ MIC Compiler       │
│ files, symbols,    │
│ relations, tests   │
└─────────┬──────────┘
          │
          ▼
┌────────────────────┐
│ .mic Memory File   │
│ portable, local,   │
│ inspectable        │
└─────────┬──────────┘
          │
          ▼
┌────────────────────┐
│ Symbol-Aware       │
│ Retrieval          │
└─────────┬──────────┘
          │
          ▼
┌────────────────────┐
│ Context Pack       │
│ evidence + lines   │
└─────────┬──────────┘
          │
          ▼
┌────────────────────┐
│ Local Gemma 4      │
│ Ollama / llama.cpp │
└────────────────────┘

MICode Tutor is designed for low-connectivity and privacy-sensitive environments.

A realistic deployment is:

one local classroom server
+ quantized Gemma 4 model
+ Ollama or llama.cpp
+ shared .mic course repositories
+ many students using lightweight terminals

Students do not need cloud API keys.
Private code does not leave the machine.
Teachers can distribute .mic memory files with course repositories.

MICode Tutor v0.1 is a research alpha.

It is not a replacement for Cursor, Claude Code, or full autonomous coding agents.

It demonstrates a focused capability:

Compile a repository into portable machine memory so local Gemma 4 can explain, teach, test, and plan safely offline.

• Python-focused parser in v0.1.
• Retrieval is lightweight and symbolic-textual, not learned neural retrieval.
• Patch generation is proposal-only and does not apply edits.
• Local inference speed depends on model size, quantization, runtime, and hardware.
• Offline model setup still requires a local GGUF or preinstalled runtime.

• richer multi-language parsers,
• MCP server integration,
• LangChain / LlamaIndex retriever adapters,
• GitHub Action to generate .mic on pull requests,
• offline classroom bundle,
• improved benchmark suite,
• learned neural MIC compiler research,
• GUI / lightweight web UI,
• safer patch application with sandboxed test execution.

Codebases should be compiled into machine-interpretable memory before agents reason over them.

MICode Tutor is the first small step toward that idea.

MIT License.

If you use MICode Tutor, please cite:

MICode Tutor: Offline Codebase Memory for Gemma 4.
Built for the Google DeepMind Gemma 4 Good Hackathon, 2026.
```# MICode-Tutor

## Research Lineage: Machine-Interpretable Information

MICode Tutor is an applied engineering step toward a broader research idea: **Machine-Interpretable Information (MII)**.

The core hypothesis is that documents and codebases should not be treated as disposable prompt text. They should be compiled into persistent, machine-interpretable memory artifacts before AI agents reason over them.

For this hackathon prototype, `.mic` is an inspectable symbolic-textual code memory artifact. It does not require hidden `.mii` neural states. Future versions may explore richer neural protocol states, but v0.1 is intentionally transparent, local, and auditable.

See [docs/MII_RELATION.md](docs/MII_RELATION.md) for more.